SpringBoot 项目整合 Swagger2

零、前言

0. 本文项目环境：Maven、SpringBoot
1. 官网连接传送门：https://swagger.io/
2. Maven 仓库传送门：https://mvnrepository.com/

一、Swagger 作用

Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

从官网的这段话中可以看出，Swagger 的作用主要是简单、快速地为正在研发的项目提供 API 接口文档。

经实际体验后，Swagger的作用也非常明显，可以通过注解的方式，直接生成在线 API 文档，基于该文档可以有很多好处：

1. 方便开发者对接口的调用测试
2. 为前端开发者理解后端服务接口提供通道
3. 便于接口管理
4. 其他

所以，建议使用。

二、Swagger 依赖

可以在 Maven仓库 中找到对应的Swagger依赖包并可查看版本，需要导入的依赖包为 springfox-swagger2 和 springfox-swagger-ui。

示例：
在 SpringBoot 项目的 pom.xml 文件中加入依赖，这里选取较多人用的近期版本：

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

三、Swagger 配置

导入依赖之后，需要在项目的config包中新建 SwaggerConfig 类，便于配置 Swagger。

常用配置见示例，如下：

// com.alun.demo.config.SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean swaggerEnable;      //通过配置文件设置是否使用Swagger

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)                  // 是否启用 swagger2
                .apiInfo(apiInfo())                     // 文档说明
                .select()
                //.securitySchemes()                    // API文档保护，本例中不需要
                .apis(RequestHandlerSelectors.basePackage("com.alun.demo"))      // 扫描API信息的包入口
                .paths(PathSelectors.any())             // 路径过滤器，可以选择任意，即全部扫描
                .build();
    }

    /**
     * 生成文档的说明信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Project Demo API Doc")                                  // 文档标题
                .description("示例项目的接口文档。")                               // 文档描述
                .contact(new Contact("alun","https://blog.youkuaiyun.com/weixin_36406616","alun@example.com"))      // 项目联系人
                .termsOfServiceUrl("https://blog.youkuaiyun.com/weixin_36406616")    // 可填项目维护/更新文档地址等
                .version("1.0.0")                                              // API文档版本号
                .build();
    }
}

四、Swagger 注解

• 注解一览

  注解	作用	常用属性
  @Api	用在接口类上，表示对类的说明	tags 可对该类接口定义业务说明，在页面中显示
  @ApiOperator	用在接口方法上，说明方法的作用	value 说明方法的作用； notes 是方法的备注说明
  @ApiImplicitParams	用在接口方法上，用来组合多组 @ApiImplicitParam 注解	用法：在 @ApiImplicitParams({…}) 中间可以写多组 @ApiImplicitParam
  @ApiImplicitParam	用在接口方法上，表示对入参列表的说明	name表示参数名；value 表示对参数的说明；required表示参数是否为必传；paramType表示参数的位置(如 header、query、path、body、form)；dataType 表示参数类型，默认为String
  @ApiResponses	用在接口方法上，用来组合多组 @ApiResponse 注解	用法：@ApiResponses({…}) 中间写入多组 @ApiResponse
  @ApiResponse	用在接口方法上，表示对响应码的描述	code表示响应码，如404 ； message 表示对响应码的说明
  @ApiModel	用在接口实体类上，表示对类的说明	value表示对象名；description对该对象的描述
  @ApiModelProperty	用在实体类的属性上，表示对属性的说明	value表示字段含义；name属性名；dataType 属性类型；required是否为必填；example举例说明；hidden隐藏该属性

• 示例（实体类）

  @Data
  @ApiModel("接口信息参数类")
  public class Info {
      @ApiModelProperty(value = "信息参数Id", required = true, example = "100001")
      private int Id;
  
      @ApiModelProperty(value = "信息", required = true, example = "接口的测试信息")
      private String msg;
  }
  

• 示例（接口类）

  @RestController
  @ResponseBody
  @Api("IndexController API")
  public class IndexController {
      @RequestMapping(value = "/test1", method = RequestMethod.GET)
      @ApiOperation(value = "Swagger 无参测试接口")
      public String test1() {
          return "Hello! Alun.";
      }
  
      @RequestMapping(value = "/test2", method = RequestMethod.POST)
      @ApiOperation(value = "Swagger 有参测试接口")
      public String test2(@RequestBody Info info) {
          return info.getMsg();
      }
  }
  

五、Swagger 访问（结果示例）

• 接口源信息
  访问路径：

  项目服务地址 + /v2/api-docs
  

  示例

  http://localhost:8080/v2/api-docs
  

• 可视化 API 文档

  项目服务地址 + /swagger-ui.html
  

  示例：

  http://localhost:8080/swagger-ui.html
  

  本博文项目Demo具体页面示例：