SpringBoot 集成 Swagger

实验环境

IDEA
Spring Boot：2.4.4
SpringFox：3.0.0
Gradle：6.8.3

Swagger 和 SpringFox

Swagger 是一个规范和完整的框架，用于创建、描述、调试话和可视化 RESTful 风格的 Web 服务。通俗地说，Swagger 是一个主要甩来在线创建文档的插件，主要用来高质量地动态生成 API 接口供前后端进行交互和在线闹试接口。
SpringFox 是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在 spring boot 中使用。
SpringFox3.0.0 新特性
Spring5，Webflux 支持（仅支持请求映射，尚不支持功能端点）；
Spring Integration 支持；
springboot 支持 springfox Boot starter 依赖性（零配置、自动配置支持）；
具有自动完成功能的文档化配置属性；
更好的规范兼容性与2.0；
支持 OpenApi 3.0.3；
零依赖（几乎只需要 spring-plugin，pswagger-core，现有的 swagger2 注释将继续工作并丰富 openapi3.0 规范。

Spring Boot 集成 Swagger

实验前提：已经使用 idea 新建 Spring Boot 工程，建构工具使用Gradle；
在 build.gradle 文件中 dependencies 中添加 springfox 依赖：现在非常方便，不像以往版本需要好几个依赖，现在只需添加一个
```
implementation 'io.springfox:springfox-boot-starter:3.0.0'
```

编写测试接口

TestController.java

   package club.lacerate.blog.controller;
   
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   import java.util.Map;
   
   
   @Api(tags="测试接口类")
   @RestController
   @RequestMapping("/api/test")
   public class TestController {
   
       @ApiOperation("测试接口")
       @GetMapping(value = "/test")
       public Map<String, Object> Test() {
           return null;
       }
   
   }

Spring Boot 启动类中添加注解 @EnableOpenApi 开启 swagger 的自动配置

BlogApplication.java

   package club.lacerate;
   
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import springfox.documentation.oas.annotations.EnableOpenApi;
   
   @EnableOpenApi
   @SpringBootApplication
   public class BlogApplication {
   
       public static void main(String[] args) {
           SpringApplication.run(BlogApplication.class, args);
       }
   
   }

运行工程；待工程启动后，访问 http://localhost:8080/swagger-ui/index.html 就可以看到swagger页面啦！

集成成功！

Spring Boot 配置 Swagger

编写Swagger配置类

SwaggerConfig.java

   package club.lacerate.common.config;
   
   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.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   
   /**
    * Swagger 配置类
    *
    * @author zhaoff
    */
   @EnableOpenApi
   @Configuration
   public class SwaggerConfig {
   
       /**
        * 创建API应用
        *
        * @return API应用
        */
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.OAS_30)
                   .apiInfo(apiInfo())
                   // 是否开启swagger
                   .enable(true)
                   .select()
                   // 扫描路径设置
                   .apis(RequestHandlerSelectors.basePackage("club.lacerate.blog.controller"))
                   // 处理路径设置
                   .paths(PathSelectors.any())
                   .build();
       }
   
       /**
        * 创建API的基本信息
        *
        * @return API的基本信息
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("Lacerate Blog 接口文档")
                   .description("Lacerate Blog 接口文档 1.0")
                   // 开发者信息
                   .contact(new Contact("foleyZhao", "https://gitee.com/FoleyZhao", "foleyzhao@163.com"))
                   .version("1.0.0")
                   .build();
       }
   
   }

访问 http://localhost:8080/swagger-ui/index.html

配置生效！

Swagger 的常用注解

@Api()

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源
参数：

tags = {"该方法的作用1","该方法的作用2"}  // 如果设置这个值、value 的值会被覆盖
value = "url 的路径值"
description = "对 api 资源的描述"

其他不常用参数：

属性名称	备注
basePath	基本路径
position	如果配置多个 Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为 true ，将在文档中隐藏

@ApiOperation()

用于方法，表示对方法的说明
参数：

value = "方法的用途和作用"
notes = "方法的注意事项和备注"
tags = {"该方法的作用1","该方法的作用2"}

@ApiModel()

用于响应实体类上，用于说明实体作用
参数：

description = "描述实体的作用"

@ApiModelProperty

用在属性上，描述实体类的属性的含议
参数：

value = "描述参数的意义"
name = "参数的变量名"
required = true  // 参数是否必选

@ApiImplicitParams

用在请求的方法上，表示对方法的参数的说明，
一个 @ApiImplicitParams 包含多个 @ApiImplicitParam

@ApiImplicitParam

用于方法，表示对单个请求参数的说明
参数：

name = "参数名" 
value = "参数说明" 
dataType = "参数类型"  // 默认 String, 其它值 dataType="Integer"
paramType = "query" // 表示参数放在哪里
    可选值
    · header 请求参数的获取：@RequestHeader
    · query 请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（请求体，不常用）
    · form（普通表单提交，不常用） 
defaultValue = "参数的默认值"
required = "true"  // 参数是否必选

@ApiParam()

用于方法，参数，字段说明，表示对参数的要求和说明
参数：

name = "参数名称"
value = "参数的简要说明"
defaultValue = "参数默认值"
required = "true" // 参数是否必选，默认为false

@ApiResponses

用于请求的方法上，表示对方法返回值的说明，根据响应码表示不同响应
一个 @ApiResponses 包含多个 @ApiResponse

@ApiResponse

用在请求的方法上，表示对方法返回值的说明
参数：

code = "404"  // 表示响应码(int型)，可自定义
message = "状态码对应的响应信息"
response = 抛出异常的类

@ApiIgnore()

用于类或者方法上，不被显示在API文档页面上

@Profile({“dev”, “test”})

用于配置类上，表示只对开发和测试环境有用

HappyNewYear's Blog

SpringBoot 集成 Swagger

SpringBoot 集成 Swagger

实验环境

Swagger 和 SpringFox

Spring Boot 集成 Swagger

Spring Boot 配置 Swagger

Swagger 的 常用注解

@Api()

@ApiOperation()

@ApiModel()

@ApiModelProperty

@ApiImplicitParams

@ApiImplicitParam

@ApiParam()

@ApiResponses

@ApiResponse

@ApiIgnore()

@Profile({“dev”, “test”})

Swagger 的常用注解