Spring Boot 整合 Swagger2 接口文档引擎

本文首发于：https://antoniopeng.com

引入依赖

在 pom.xml 中添加 swagger2 所需依赖，代码如下:

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

相关配置

• 创建 Swagger2Config 配置类，代码如下：

  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;
  
  @Configuration
  public class Swagger2Config {
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("xxx.xxx.controller"))
                  .paths(PathSelectors.any())
                  .build();
      }
  
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("标题")
                  .description("描述")
                  .termsOfServiceUrl("网址")
                  .version("版本号")
                  .build();
      }
  }
  

  注意： RequestHandlerSelectors.basePackage("xxx.xxx.controller") 为 Controller 包路径，不然生成的文档扫描不到接口

• Application 入口类中添加注解

  加上注解 @EnableSwagger2 表示开启 Swagger，代码如下：

  @EnableSwagger2
  @SpringBootApplication
  public class ServiceAdminApplication {
      public static void main(String[] args) {
          SpringApplication.run(ServiceAdminApplication.class, args);
      }
  }
  

使用 Swagger2

在 Controller 中添加 Swagger 相关注解，示例代码如下:

@ApiOperation(value = "分页查询")
@ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "pageSize", value = "页数", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "UserJson", value = "对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
})
@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
public BaseResult page(
    @PathVariable(required = true) int pageNum, 
	@PathVariable(required = true) int pageSize,
    @RequestParam(required = false) String UserJson
){
    return null;
}

Swagger 访问地址：http://ip:port/swagger-ui.html

Swagger 相关注解说明

• @Api：修饰整个类，描述 Controller 的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP 响应其中 1 个描述
• @ApiResponses：HTTP 响应整体描述
• @ApiIgnore：使用该注解忽略这个 API
• @ApiError：发生错误返回的信息

END