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;
}