Spring Boot接口：用Swagger3实现接口文档
在生成接口文档之前，先了解下前置知识：OpenAPI规范，Swagger，SpringFox，Knife4J，Swagger UI等之间的关系。
一、OpenAPI规范(OAS)
OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。
此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。
二、什么是Swagger？
Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。
Swagger的3个重要作用：
- 将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；
- 当接口更新之后，只需要修改代码中的Swagger描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；
- 通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。
三、Swagger和SpringFox有啥关系？
Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则是这项技术的具体实现。
四、什么是Knife4J和Swagger什么关系？
本质是Swagger的增强解决方案，前身只是一个SwaggerUI（swagger-bootstrap-ui）
五、实现案例之Swagger3
step1: 引入Swagger3依赖包
<!--Swagger3-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
step2: 创建Swagger配置类
package com.kyk.imoocmall.config;
import io.swagger.annotations.ApiOperation;
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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @FileName imooc-mall
* @Author keyongkang
* @Create 2022-11-29-14:33
*/
@Configuration
public class SwaggerConfig {
/**
* @return swagger config
*/
@Bean
public Docket openApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kyk.imoocmall.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* @return api info
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Imooc Mall Swagger API")
.description("test api")
.termsOfServiceUrl("http://localhost:8080/")
.version("1.0")
.build();
}
}
- 代码解释
- @Configuration：让Spring来加载该类配置
- apiInfo()：用来展示该API的基本信息
- select()：返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露给Swagger来展现
- .apis(RequestHandlerSelectors.basePackage())：配置包扫描路径。Swagger会扫描包下所有Controller定义的API，并产生文档内容。如果不想产生API，则使用注解@ApiIgnore
step3:开启Swagger3
在springboot的启动类型添加注解 @EnableOpenApi
package com.kyk.imoocmall;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;
@EnableOpenApi
@SpringBootApplication
@MapperScan("com.kyk.imoocmall.mapper")
public class ImoocMallApplication {
public static void main(String[] args) {
SpringApplication.run(ImoocMallApplication.class, args);
}
}
step4:访问Swagger3
直接访问：http://localhost:8080/swagger-ui/
六、编写接口文档
在完成上述配置后，即生成了文档，但是这样生成的文档主要针对请求本身，而描述自动根据方法等命名产生，对用户并不友好。所以，通常需要自己增加一些说明以丰富文档内容。可以通过以下注解来增加说明。
Swagger常用注解
- @Api：描述类/接口的主要用途
- @ApiOperation：描述方法用途，给API增加说明
- @ApiImplicitParams和@ApiImplicitParam: 在 Rest 接口方法上使用来指定请求参数
- @ApiIgnore: 可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
- @ApiModel :类注解,在返回和参数实体类添加此注解,可以对返回和参数实体类进行说明
- @ApiModelProperty: 参数注解
@RequestMapping("/userController")
@RestController
@Api(value = "用户")
public class UserController {
@Autowired
private UserFeign userFeign;
/**
* 获取参数
* @return
*/
@ApiOperation(value = "查询用户")
@ApiImplicitParams({
@ApiImplicitParam(dataType = "string",name = "name",value = "用户名")
})
@GetMapping("userShow")
public List<UserCommon> userShow(@ApiParam(value = "用户名",required = true) @RequestBody UserVo userCommon){
return userFeign.show();
}
}
@ApiModel("用户vo")
@Data
public class UserVo {
private int id;
@ApiModelProperty(value = "编号")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
}