SpringDoc介绍
一、SpringDoc
官方文档
1.1何为SpringDoc
SpringDoc是一个用来自动生成API文档的库。它是基于SpringBoot项目的，遵循OpenAPI3(一个组织规定的规范)规范。它是通过检查我们运行中的程序，推断出基于Spring配置、类结构和各种注解的API语义，从而自动生成JSON、YAML和HTML格式的接口文档。
而我们不得不提的就是Swagger。Swagger是一个公司的开源项目，将自己的API设计贡献给了OpenAPI并由其标准化。在SpringDoc之前我们还可以使用Springfox,和SpringDoc一样是一个用于生成API文档的库，2020年起不再更新。
1.2添加SpringDoc
我们现在学习SpringDoc的使用。
我们添加SpringDoc的依赖。
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version>
</dependency>而在我们的项目运行之后，我们按照下面链接的格式访问即可。其中有一些常量我们可以自己设置。(html格式)
http://server:port/context-path/swagger-ui.html一般来说有如下。
http://localhost:8080/swagger-ui.html当然我们也可以去访问json的或yml的，但是不好看。 而且不能进行发请求。
我们可以在yml文件当中去配置一些信息。
springdoc:api-docs:# 是否开启接口文档enabled: trueswagger-ui:# 持久化认证数据persistAuthorization: trueinfo:# 标题title: '标题：${demo.name}多租户管理系统_接口文档'# 描述description: '描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...'# 版本version: '版本号: ${demo.version}'# 作者信息contact:name: Agazigiemail: 123456789@qq.comurl: www.baidu.comcomponents:# 鉴权方式配置security-schemes:apiKey:type: APIKEYin: HEADERname: ${sa-token.token-name}#这里定义了两个分组，可定义多个，也可以不定义group-configs:- group: 1.演示模块packages-to-scan: org.dromara.demo- group: 2.通用模块packages-to-scan: org.dromara.web- group: 3.系统模块packages-to-scan: org.dromara.system- group: 4.代码生成模块packages-to-scan: org.dromara.generator1.3使用SpringDoc
我们先完成一个简单的Controller层。
接着我们访问上边的路径。
1.4详解SpringDoc
1.4.1文档信息设置
步骤一：创建API文档配置类。
步骤二：将OpenAPI对象交给IoC容器管理。
步骤三：对OpenAPI对象进行设定。
1.4.2常用注解
| 注解 | 含义 |
|---|---|
| @Tag | 用在controller类上，描述此controller的信息 |
| @Operation | 用在controller的方法里，描述此api的信息 |
| @Parameter | 用在controller方法里的参数上，描述参数信息 |
| @Parameters | 用在controller方法里的参数上 |
| @Schema | 用于Entity，以及Entity的属性上 |
| @ApiResponse | 用在controller方法的返回值上 |
| @ApiResponses | 用在controller方法的返回值上 |
| @Hidden | 用在各种地方，用于隐藏其api |
| @NotNull、@Min、@Max | 非空、值的最大、最小 |
1.4.3注解简化
1.4.4配置认证
步骤一：Application启动类上加@SecurityScheme，并设置信息。
步骤二：添加其配置。
步骤三：设计过滤器。
步骤四：验证结果。
1.4.5文档分组
1.4.6配置信息
