SpringDoc介绍

news2025/11/1 7:46:36

一、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: true
    swagger-ui:
      # 持久化认证数据
      persistAuthorization: true
  info:
    # 标题
    title: '标题：${demo.name}多租户管理系统_接口文档'
    # 描述
    description: '描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...'
    # 版本
    version: '版本号: ${demo.version}'
    # 作者信息
    contact:
      name: Agazigi
      email: 123456789@qq.com
      url: www.baidu.com
  components:
    # 鉴权方式配置
    security-schemes:
      apiKey:
        type: APIKEY
        in: HEADER
        name: ${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	非空、值的最大、最小