Swagger

一、Swagger基础

Swagger官网：https://swagger.io (opens new window)

1.1 Swagger作用

Swagger提供了一套规范，用于解决前后端接口文档的编写及维护。

通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。

1.2 Spring整合Swagger

作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

Springfox Swagger：Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。

二、Swagger注解

2.1 常用注解

Swagger2	Swagger3	注解位置
@Api(tags=“接口描述”)	@Api(tags=“接口描述”)	controller类上
@ApiOperation(value = “接口方法描述”)	@Operation(summary = “接口方法描述”)	controller 方法上
@ApiModelProperty(value = “字段描述”)	@ApiModelProperty(value = “字段描述”)	JavaBean的字段上
@ApiModel(“实体类的描述”)	@ApiModel(“实体类的描述”)	JavaBean上
@EnableSwagger2	@EnableOpenApi	配置类上
@ApiImplicitParams	@ApiImplicitParams	controller的方法参数中
@ApiImplicitParam	@ApiImplicitParam	@ApiImplicitParams 下的的子参数
@ApiParam(name = “参数描述”)	@Parameter(description = “参数描述”)	controller 方法的参数中

2.2 Swagger2注解

• @Api：修饰整个类，描述 Controller 的作用

• @ApiOperation：描述一个类的一个方法，或者说一个接口

• @ApiParam：单个参数描述

• @ApiModel：用对象来接收参数

• @ApiProperty：用对象接收参数时，描述对象的一个字段

• @ApiResponse：HTTP 响应其中 1 个描述

• @ApiResponses：HTTP 响应整体描述

• @ApiIgnore：使用该注解忽略这个API

• @ApiError：发生错误返回的信息

• @ApiImplicitParam：一个请求参数

• @ApiImplicitParams：多个请求参数

1. @Api

说明：

用在请求的类上，表示对类的说明

常用参数：

• tags="说明该类的作用，非空时将覆盖 value 的值"
• value="描述类的作用"

其他参数：

• description 对 api 资源的描述，在 1.5 版本后不再支持

• basePath 基本路径可以不配置，在 1.5 版本后不再支持

• position 如果配置多个 Api 想改变显示的顺序位置，在 1.5 版本后不再支持

• produces 设置 MIME 类型列表（output），例："application/json, application/xml"，默认为空

• consumes 设置 MIME 类型列表（input），例："application/json, application/xml"，默认为空

• protocols 设置特定协议，例：http， https， ws， wss

• authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。

• hidden 默认为 false，配置为 true 将在文档中隐藏

示例：

@Api(tags="登录请求")
@Controller
public class TestController {}

2. @ApiOperation

说明：

用在请求的方法上，说明方法的用途、作用

常用参数：

• value="说明方法的用途、作用"
• notes="方法的备注说明"

其他参数：

• tags 操作标签，非空时将覆盖value的值

• response 响应类型（即返回对象）

• responseContainer 声明包装的响应容器（返回对象类型）。有效值为 "List", "Set" or "Map"。

• responseReference 指定对响应类型的引用。将覆盖任何指定的response（）类

• httpMethod 指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"

• position 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持

• nickname 第三方工具唯一标识，默认为空

• produces 设置MIME类型列表（output），例："application/json, application/xml"，默认为空

• consumes 设置MIME类型列表（input），例："application/json, application/xml"，默认为空

• protocols 设置特定协议，例：http， https， ws， wss。

• authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。

• hidden 默认为false， 配置为true 将在文档中隐藏

• responseHeaders 响应头列表

• code 响应的HTTP状态代码。默认 200

• extensions 扩展属性列表数组

示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

3. @ApiImplicitParams

说明：

用在请求的方法上，表示一组参数说明；@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面

常用参数：

• name：参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致

• value：参数的汉字说明、解释

• required：参数是否必须传，默认为 false （路径参数必填）

• paramType：参数放在哪个地方

  • header 请求参数的获取：@RequestHeader

  • query 请求参数的获取：@RequestParam

  • path（用于 restful 接口）--> 请求参数的获取：@PathVariable

  • body（不常用）

  • form（不常用）

• dataType：参数类型，默认 String，其它值 dataType="Integer"

• defaultValue：参数的默认值

其他参数（@ApiImplicitParam）：

• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值

• access 允许从API文档中过滤参数。

• allowMultiple 指定参数是否可以通过具有多个事件接受多个值，默认为 false

• example 单个示例

• examples 参数示例。仅适用于 BodyParameters

示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "用户名", required = false, paramType = "query", dataType = "String"),
    @ApiImplicitParam(name = "pass", value = "密码", required = false, paramType = "query", dataType = "String")
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

4. @ApiModel

说明：

用于响应类上，表示一个返回响应数据的信息（这种一般用在 POST 创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）；@ApiModelProperty：用在属性上，描述响应类的属性

其他参数(@ApiModelProperty)：

• value 此属性的简要说明。

• name 允许覆盖属性名称

• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值

• access 允许从 API 文档中过滤属性。

  • notes 目前尚未使用。

• dataType 参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。

• required 参数是否必传，默认为 false

• position 允许在类中对属性进行排序。默认为 0

• hidden 允许在 Swagger 模型定义中隐藏该属性。

• example 属性的示例。

• readOnly 将属性设定为只读。

• reference 指定对相应类型定义的引用，覆盖指定的任何参数值

示例：

@ApiModel(value="用户登录信息", description="用于判断用户是否存在")
public class UserModel implements Serializable{
   private static final long serialVersionUID = 1L;
   /**
    * 用户名
    */
   @ApiModelProperty(value="用户名")
   private String account;
   /**
     * 密码
     */
    @ApiModelProperty(value="密码")
   private String password;
}

5. @ApiResponses

说明：

用在请求的方法上，表示一组响应；@ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息

常用参数：

• code：数字，例如 400

• message：信息，例如 "请求参数没填好"

• response：抛出异常的类

示例：

@PostMapping(value="/update/{id}")
@ApiOperation(value = "修改用户信息",notes = "打开页面并修改指定用户信息")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
public JsonResult update(@PathVariable String id, UserModel model){}

6. @ApiParam

说明：

用在请求方法中，描述参数信息

常用参数：

• name：参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致

• value：参数的简要说明。

• defaultValue：参数默认值

• required：属性是否必填，默认为 false （路径参数必须填）

示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "model", value = "用户信息Model") UserModel model){}

其他参数：

• allowableValues 限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值

• access 允许从 API 文档中过滤参数。

• allowMultiple 指定参数是否可以通过具有多个事件接受多个值，默认为 false

• hidden 隐藏参数列表中的参数。

• example 单个示例

• examples 参数示例。仅适用于 BodyParameters

示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false) @RequestParam(value = "name", required = false) String account,
    @ApiParam(name = "pass", value = "密码", required = false) @RequestParam(value = "pass", required = false) String password){}

2.3 Swagger3注解

三、Swagger开发

3.1 SpringBoot整合Swagger2.x

1. 添加依赖

 <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
 </dependency>

 <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
 </dependency>

• springfox-swagger2：自动生成描述API的json文件
• springfox-swagger-ui：用一种友好的界面呈现json文件

2. 创建一个SwaggerConfig配置文件

该配置用于告诉springfox，生成swagger的一些参数配置。

package com.zhou.swagger2.config;

import com.google.common.base.Predicates;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2) // 指定生成Swagger2规范的文档
                .groupName("webApi") // 
                .apiInfo(webApiInfo()) // 描述文档的主题信息
                .select() // 接口选择器
            	// 设置哪些接口会映射到Swagger文档中
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
            	// 告诉springfox，哪些包下的接口要生成Swagger文档
                .apis(RequestHandlerSelectors.basePackage("com.zhou"))
                .build();
    }
    /**
    * 文档的主题信息，会在Swagger UI 中呈现
    */
    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("网站-中心API文档")
                .description("本文档描述了接口定义")
                .version("1.0")
                .contact(new Contact("hello", "https://blog.csdn.net/u013010499",
                        "6666666666@qq.com"))
                .build();
    }

}

访问：http://localhost:8080/swagger-ui.html (opens new window)

3. 注解配置HTTP接口

• @Api(tags="欢迎接口") 作用于类上

• @ApiOperation(value = "一个Rest") 作用于方法上

• @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true) 作用于参数

4. 注解配置实体类

• @ApiModel 标识当前实体

• @ApiModelProperty(value = "用户id") 标识当前实体的属性字段

3.2 SpringBoot整合Swagger3.x

swagger3与swagger2的差异在于:

• 配置文件上添加的注解是@EnableOpenApi，而swagger2是@EnableSwagger2；
• 访问地址http://localhost:8080/swagger-ui/index.html (opens new window)，而swagger2是http://localhost:8080/swagger-ui.html
• pom引入的依赖包只有一个 springfox-boot-starter，而swagger2有两个springfox-swagger2 、springfox-swagger-ui。

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. 创建配置类

package com.zhou.swagger3.config;

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

@EnableOpenApi //启用swagger
@Configuration
public class Swagger3Config implements WebMvcConfigurer {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //只有在接口上加了Operation注解才展示
                //.apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) 
                .paths(PathSelectors.any())
                .build()
                //.globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResonseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResonseMessage());
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("联系")
                .contact(new Contact("牧歌ing", "https://blog.csdn.net/u013010499", "666666@qq.com"))
                .version("1.0")
                .build();
    }

    private List<Response> getGlobalResonseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
         return responseList;
    }
}

访问：http://localhost:8080/swagger-ui/index.html (opens new window)

3. 注解配置HTTP接口

• @Api(tags="欢迎接口") 作用于类上

• @Operation(summary = "一个Rest") 作用于方法上

• @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true) 作用于参数

4. 注解配置实体类

• @ApiModel 标识当前实体

• @ApiModelProperty(value = "用户id") 标识当前实体的属性字段

5. application.properties

# 在测试环境中用到，生产环境需设置为false
springfox.documentation.swagger-ui.enabled=true
server.port=8081