日常开发过程中接口文档是必不可少得一项工作,由于接口增加、变更使得文档变得难以维护,也容易忘记或漏掉接口,说实话大部分开发者也不太愿意去维护这么个文档,还有就是接口测试角度分析,通常我们开发完一个接口需要使用接口调用工具postman等等http调用工具来做接口的测试,swagger的出现简直就是我们开发者的福音,swagger可自动为我们生成接口文档页面,可在页面直接查看接口入参、出参以及做接口测试,话不多说接下来我们就来看看SpringBoot项目是如何接入swagger api文档神器的。
提示:以下是本篇文章正文内容,下面案例可供参考
@Api 写在controller类上,入参API接口名称/介绍
@ApiOperation 用在接口方法上,入参接口名称/介绍
@ApiModel 用在数据实体类上,入参实体类名称/介绍
@ApiModelProperty 用在对象数据实体属性上,入参属性名称/介绍
@ApiParam 单个请求参数说明
@ApiImplicitParams 接口参数说明
@ApiResponses 接口响应提示(比如400参数不对等等注释)
@ApiIgnore 忽略接口方法
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
dependency>
①controller类
package com.example.demo.controller;
import com.example.demo.dao.JdbcPersonDao;
import com.example.demo.dto.JsonDataDTO;
import com.example.demo.model.PersonDO;
import com.example.demo.service.PersonService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Api("swagger3演示controller")
@RestController
@RequestMapping("/")
public class DemoController {
@Autowired
private PersonService personService;
@Autowired
private JdbcPersonDao jdbcPersonDao;
@ApiOperation("test接口")
@PostMapping("/test")
public String test(@RequestBody PersonDO personDO) {
return "实体类入参demo";
}
@ApiOperation("test接口")
@GetMapping("/test")
public String test() {
return "Hello World";
}
@ApiOperation("getJsonData接口")
@GetMapping("/getJsonData")
public JsonDataDTO getJsonData() {
JsonDataDTO jsonDataDTO = new JsonDataDTO();
jsonDataDTO.setName("张三");
jsonDataDTO.setAge(18);
jsonDataDTO.setSex("男");
return jsonDataDTO;
}
@ApiOperation("globalExceptionTest接口")
@GetMapping("/globalExceptionTest")
public void globalExceptionTest() throws Exception {
throw new Exception("发生异常啦!!!");
}
@ApiOperation("selectPersonInfo接口")
@GetMapping("/selectPersonInfo")
public PersonDO selectPersonInfo(@RequestParam("id") @ApiParam("主键ID") Long id) {
return personService.selectPersonInfo(id);
}
@ApiOperation("selectPersonInfoJpaDemo接口")
@GetMapping("/selectPersonInfoJpaDemo")
public PersonDO selectPersonInfoJApademo(@RequestParam("id") @ApiParam("主键ID") Long id) {
return jdbcPersonDao.getPersonDO(id);
}
@ApiOperation("queryDataForJdbc接口")
@GetMapping("/queryDataForJdbc")
public PersonDO queryDataForJdbc(@RequestParam("id") @ApiParam("主键ID") Long id) {
return personService.selectPersonInfoJpaDemo(id);
}
}
②接口参数对象DTO
package com.example.demo.dto;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel("swagger接口对象实体类")
@Data
public class JsonDataDTO {
/**
* 姓名
*/
@ApiModelProperty("姓名")
private String name;
/**
* 年龄
*/
@ApiModelProperty("年龄")
private Integer age;
/**
* 性别
*/
@ApiModelProperty("性别")
private String sex;
}
package com.example.demo.config;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.HashSet;
@EnableOpenApi
@Configuration
public class SwaggerConfiguration {
@Value("server.port")
private String port;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定义是否开启swagger,false为关闭,可以通过变量控制
.enable(true)
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host("http://localhost:"+port)
// 选择哪些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(getProtocols("https", "http"));
}
private HashSet<String> getProtocols(String https, String http) {
HashSet set = new HashSet<String>();
set.add(https);
set.add(http);
return set;
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("Demo Api Doc")
.description("rest接口文档 lc")
.version("v1.0")
.build();
}
}
比如项目中登录拦截器,安全框架拦截等等,需要排除swagger路径不然可能会被拦截导致访问不了swagger界面。
/swagger**/**
/webjars/**
/v3/**
/doc.html
POST请求接口,点右上角Try it out 可编辑入参并Execute做接口测试,往下就是响应信息,从图片我们可以看到代码中注释说明/名称。
GET请求接口,点右上角Try it out 可编辑入参并Execute做接口测试,往下就是响应信息,从图片我们可以看到代码中注释说明/名称。
有到了总结时刻了,一句话:简直太好用啦!快点把它引入到你们项目当中,减少工作量!!!