为什么要聊Swagger呢，原因是我发现实际开发中前端同事每次都需要问我枚举是什么，经过反思，我觉得是接口文档写的不够好。所以整理一下如何用Swagger注解生成一个好的接口文档。

常用swagger注解

类注解

最常用的类注解是@Api，它的作用是标注这个类是用来干嘛的，不写默认是Controller的类名用-连接，不太好理解。差别如下：

**@Api**中最重要的参数是tags，其他的值可以不写，示例：

@RestController
@RequestMapping("/subject")
@Slf4j
@Api(tags = "题目管理")
public class SubjectController {// 省略
}

方法注解

最常用的方法注解是@ApiOpertion，它的作用是描述接口的作用和请求方式。不写默认就是方法名，也是不好理解。差别如下：

这个注解重要的两个参数value跟httpMethod

@PostMapping("/add")
@ApiOperation(value = "新增题目", httpMethod = "POST")
public Result<Boolean> add(@RequestBody SubjectInfoDTO subjectInfoDTO) {// 省略
}

字段注解

最常用的字段注解是@ApiModelProperty,这个注解的需要关注的参数有几个：

@ApiModelProperty(value = "分类id",required = true,example = "1",allowableValues = "1,2,3,4,5")
private Long categoryId;

1. value：对应下图中的参数说明
2. required：是否必填，默认是false
3. example：示例值
4. allowableValues：枚举值

Swagger配置

首先用Swagger的前提是项目里集成了swagger相关的依赖。相关步骤如下：

引入依赖

目前swagger有2种不同的UI，分别对应不同的pom依赖，两种都可以，建议使用本文的这种，增强版的UI更好用。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency>

编写配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.jayden.club.subject.application.controller")).paths(PathSelectors.any()).build().apiInfo(new ApiInfoBuilder().title("Jayden Club Subject API").description("Jayden Club Subject API Documentation").version("1.0.0").build());}}

代码解释，最重要的是.apis这个参数，其他照抄即可

• 注解：@Bean注解的意思是，这个方法会生成一个对象，然后把这个对象注册到Spring的应用环境里。简单来说，当你启动Spring Boot应用的时候，这个方法就会运行，它产生的Docket对象会被Spring管理起来，用来配置Swagger API文档。
• 创建Docket对象：new Docket(DocumentationType.SWAGGER_2)创建了一个新的Docket实例，指定了文档类型为Swagger 2.0。
• 配置API选择器：.apis(RequestHandlerSelectors.basePackage(“com.jayden.club.subject.application.controller”))**指定了哪些包下的API会被Swagger文档所包含。**这里选择了com.jayden.club.subject.application.controller包下的所有API。
• 配置路径选择器：.paths(PathSelectors.any())表示包含所有路径，即不限制哪些API路径会被Swagger记录。
• 设置API信息：.apiInfo(…)方法用于设置API的元信息，包括标题、描述和版本等。这些信息将显示在生成的Swagger文档中。
• 返回值：该方法最终返回一个配置完成的Docket对象，这个对象包含了生成Swagger API文档所需的所有信息。

静态资源映射

按照上面两步后在浏览器输入[http://localhost:8080/doc.html](http://localhost:8080/doc.html)就可以看到swagger的UI界面了。如果访问不了大概率是静态资源没配。配置方式如下：

@Configuration
public class GlobalConfig extends WebMvcConfigurationSupport {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");super.addResourceHandlers(registry);}// 省略其他方法}

通过请求路径可以知道我们请求的是服务上一个叫doc.html的静态文件。这里有两个问题：

1. 我们好像没有写doc.html文件，这个文件在哪里？
2. 怎么路由到doc.html？

先看第一个问题，其实这是swagger-bootstrap-ui包中已经有的页面，全局搜索doc.html即可搜索到。

第二个问题就跟上面的代码有关系了，其实把这两个参数作用讲明白就行了

• addResourceHandler(“doc.html”)：这个方法用于指定访问静态资源的URL模式。在这个例子中，它告诉Spring Boot，当请求URL匹配到doc.html时，应该将其作为一个静态资源来处理。
• addResourceLocations(“classpath:/META-INF/resources/”)：这个方法用于指定静态资源文件存放的位置。在这个例子中，它指定了静态资源位于类路径（classpath）下的/META-INF/resources/目录中。这意味着，当你访问doc.html时，Spring Boot会从该目录下查找并返回相应的文件。可以看下截图doc.html的位置。

访问swagger ui

在以上步骤后在浏览器中输入[http://localhost:8080/doc.html](http://localhost:8080/doc.html)就可以看到swagger ui的主页面。