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

1.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	非空、值的最大、最小