在SpringBoot项目中使用Swagger，自动生成API文档

一、概述

• Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。网友称为“丝袜哥”。
• 官网地址：https://swagger.io/
• 官网在线文档编辑器：https://editor.swagger.io

二、maven 依赖

2.1 官方依赖

• 官方文档中说明，要使用swagger需引入以下依赖。

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-core-asl</artifactId>
        <version>1.9.13</version>
</dependency>

2.2 三方整理

• 有人整理了在springboot中使用的依赖包

• github地址：https://github.com/SpringForAll/spring-boot-starter-swagger

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

• 注意： 我们在使用时任选一种方式即可。

三、在springboot中使用swagger

• 在引入maven依赖后，2.0以后版直接可以使用。
• 使用方法如下：
  • 查看文档JSON描述：http://localhost/v2/api-docs
  • 查看文档UI界面：http://localhost/swagger-ui/index.html
• 2.0以前版需要在XXXApplication上加入“@EnableSwaggerDoc”注解。
  • 旧版本访问地址可能也有变化（如：http://localhost/swagger-ui.html）具体以官方文档为准。

@SpringBootApplication
@EnableSwaggerDoc
public class XXXXXApplication {
}

四、文档分组配置

swagger:
  docket:
    weixin-offiaccount-api:
      title: weixin offiaccount controller
      base-package: top.yiqifu.weixin.offiaccount.controller
    weixin-miniprogram-api:
      title: weixin miniprogram restcontroller
      base-package: top.yiqifu.weixin.miniprogram.controller

五、实体模型描述

• 实体属性描述使用 @ApiModelProperty 注解

	@ApiModelProperty(value = "实体id", name = "id",dataType = "integer",required = true,example = "1")
    private Integer id;

六、接口描述

• 接口或类描述使用 @Api 注解

@Controller()
@RequestMapping("/weixin")
@Api(value = "WeixinController", tags={"微信签名认证"})
public class WeixinController {
    // ......
}

七、接口方法描述

• 方法描述使用 @ApiOperation 注解
• 参数描述使用 @ApiParam 注解

    @ApiOperation(value = "测试方法1")
    @GetMapping("test1")
    @ResponseBody
    public String test1(){
        return "111";
    }

    @ApiOperation(value = "测试方法2")
    @GetMapping("test2")
    @ResponseBody
    public String test2(@ApiParam(name="paramsMap",required = false, example = "{ \"key\": \"value\" }",value = "请求参数")
                        @RequestParam Map<String, String> paramsMap){
        return "111";
    }

八、注意问题

8.1 如果maven导入依赖失败（依赖项变红）

• 请修改 File -> Build, Execution, Deployment -> Build Tools -> Maven -> Importing -> VM options for importer 的值，例如：-Xmx1024m -Xmx2048m

8.2 如果启动时报 “Failed to start bean ‘documentationPluginsBootstrapper’;” 错，如下：

解决办法是：

• 一是配置 application.yaml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

• 二是在启动类上添加注解

@EnableSwagger2
@EnableWebMvc
public class XXXXXApplication {
}

• 三是将 SpringBoot 版本降低2.6以下，与Swagger匹配。

• 最后新版建议直接使用 springdoc 。