HL🌱数字花园

系统接口-swagger与Springdoc

2024年9月22日13分钟阅读

在现在的开发过程中还有很大一部分公司都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，或者写了代码再写文档。 还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了。 只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过Swagger，我们可以省略了这一步，而且文档出错率近乎于零， 只要你在写代码的时候，稍加几个注解，文档自动生成。

1、在控制层Controller中添加注解来描述接口信息如:

@Api("参数配置")
@Controller
@RequestMapping("/system/config")
public class ConfigController

2、在方法中配置接口的标题信息

@ApiOperation("查询参数列表")
@ResponseBody
public TableDataInfo list(Config config)
{
	startPage();
	List<Config> list = configService.selectConfigList(config);
	return getDataTable(list);
}

3、在系统工具-系统接口测试相关接口

注意：SwaggerConfig可以指定根据注解或者包名扫描具体的API

API详细说明

api标记，用在类上，说明该类的作用。可以标记一个Controller类做为Swagger文档资源，使用方式：

@Api(value = "/user", description = "用户管理")

与Controller注解并列使用。 属性配置：

ApiParam标记，请求属性，使用方式：

public TableDataInfo list(@ApiParam(value = "查询用户列表", required = true)User user)

与Controller中的方法并列使用，属性配置：

ApiResponse标记，响应配置，使用方式：

@ApiResponse(code = 400, message = "查询用户失败")

与Controller中的方法并列使用，属性配置：

ApiResponses标记，响应集配置，使用方式:

@ApiResponses({ @ApiResponse(code = 400, message = "无效的用户") })

与Controller中的方法并列使用，属性配置：

ResponseHeader标记，响应头设置，使用方法

@ResponseHeader(name="head",description="响应头设计")

与Controller中的方法并列使用，属性配置：

Swagger升级SpringDoc指南

OpenAPI 3 Library for spring-boot

由于 springfox 与 knife4j 均停止维护 bug众多 故从 4.3.0 开始 迁移到 springdoc 框架 基于 javadoc 无注解零入侵生成规范的 openapi 结构体 由于框架自带文档UI功能单一扩展性差 故移除自带UI 建议使用外置文档工具

由于框架采用 openapi 行业规范 故市面上大部分的框架均支持 可自行选择 例如: apifox postman torna 等 根据对应工具的文档接入即可

常见功能如下 其他功能自行挖掘 注意: javadoc 只能替换基础功能 特殊功能还需要使用注解实现

api-docs和swagger-ui的关系： 简单说下个人理解的api-docs和swagger-ui的关系：

api-docs是根据openapi规范生成的json文档。

swagger-ui是根据api-docs生成的可视化的页面。

所以api-docs才是根本，ui可以随意选择自己喜欢的。

引入依赖

基于javadoc从注释生成api文档的思路（一） - 掘金

对于想要启用 javadoc 支持的项目，应将以下依赖项与依赖项结合使用：springdoc-openapi-ui

 
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
    <version>1.6.14</version>
</dependency>
 
<!-- springdoc swagger ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>
 
 
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <!-- 必须添加此处配置javadoc才生效，
   注：该配置和lombok冲突，存在该配置则导致lombok编译报错 -->
        <annotationProcessorPaths>
            <path>
                <groupId>com.github.therapi</groupId>
                <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                <version>0.15.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>
 
 
<!-- springdoc插件（用于在verify阶段生成openapi.json） -->
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.3</version>
    <executions>
        <execution>
            <id>integration-test</id>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- The local url of your (json or yaml) - 需依赖springdoc-openapi-ui-->
        <apiDocsUrl>·</apiDocsUrl>
        <!-- api文件名称 -->
        <outputFileName>openapi.json</outputFileName>
        <!-- api文件输出路径（默认${project.build.directory}，即target下） -->
        <outputDir> ${project.build.directory}</outputDir>
        <!-- <outputDir>/home/springdoc/maven-output</outputDir> -->
        <!-- 是否跳过（默认false）-->
        <skip>false</skip>
    </configuration>
</plugin>
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <!--springdoc-openapi-maven-plugin插件依赖以下配置 -->
    <configuration>
        <jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
    </configuration>
    <executions>
        <execution>
            <id>pre-integration-test</id>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>post-integration-test</id>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

这种依赖关系改进了对javadoc标签和注释的支持：

  • 方法的 javadoc 注释：解析为描述@Operation

  • @return ：解析为响应描述@Operation

  • 属性的 javadoc 注释：解析为此字段的“@Schema”描述。

此依赖项基于 therapi-runtime-javadoc 库

确保启用 的注释处理器，以便启用 javadoc 对 springdoc-openapi 的支持。therapi-runtime-javadoc

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>0.15.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>

如果同时存在 swagger-annotation 描述和 javadoc 注释。将使用swagger属性

核心配置：

springdoc:
  # OpenAPI文档相关参数
  api-docs:
    # OpenAPI文档开关, true: 开启OpenAPI文档访问功能, false: 关闭。
    enabled: true
    # JSON格式的OpenAPI文档的访问路径
    path: /v3/api-docs
  # 扫描哪些包来生成OpenAPI文档, 多个包名用逗号分隔
  packages-to-scan: *
  # 路径匹配规则, API路径符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  paths-to-match: /*
  # 返回媒体类型匹配规则, 返回媒体类型符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  produces-to-match: /*
  # 请求头匹配规则, 请求头符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  headers-to-match: /*
  # 请求媒体类型匹配规则, 请求媒体类型符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  consumes-to-match: /*
  # 排除路径匹配规则, API路径符合这些匹配规则会排除在OpenAPI文档之外, 多个规则用逗号分隔
  paths-to-exclude:
  # 排除包匹配规则, 包名符合这些匹配规则会排除在OpenAPI文档之外, 多个规则用逗号分隔
  packages-to-exclude:
  # 默认请求媒体类型
  default-consumes-media-type: application/json
  # 默认返回的响应媒体类型
  default-produces-media-type: '*/*'
  # 是否禁用OpenAPI文档缓存,
  # 禁用后每次访问${springdoc.api-docs.path}都会重新生成(适合开发调试阶段)当响应会比较缓慢。
  cache.disabled: false
  # 是否显示Spring Actuator的接口
  show-actuator: false
  # 是否自动将类名生成为Tag
  auto-tag-classes: true
  # 是否包含返回ModelAndView对象的接口
  model-and-view-allowed: false
  # 是否从 @ControllerAdvice 注解获取接口的响应信息.
  override-with-generic-response: true
  # 是否开启接口分组功能, 开启后, 一个App可以生成多个OpenAPI文档, 每个文档显示一部分接口。
  api-docs.groups.enabled: true
  # 分组配置
  group-configs:
      # 分组名称
    - group: XXX
      # 同`springdoc.packages-to-scan`
      packages-to-scan: *
      # 同`springdoc.paths-to-match`
      paths-to-match: /*
      # 同`springdoc.paths-to-exclude`
      paths-to-exclude: ``
      # 同`springdoc.packages-to-exclude`
      packages-to-exclude:
      # 同`springdoc.produces-to-match`
      produces-to-match: /*
      # 同`springdoc.consumes-to-match`
      consumes-to-match: /*
      # 同`springdoc.headers-to-match`
      headers-to-match: /*
  # webjar资源的访问路径前缀
  webjars.prefix: /webjars
  # 是否翻译属性值, true: Schema中的属性的值可以用Spring的表达式来编写, 然后运行时自动转成真实的取值
  api-docs.resolve-schema-properties: false
  # 删除无效的引用定义
  remove-broken-reference-definitions: true
  # 是否格式化输出的OpenAPI文档, 方便人类阅读
  writer-with-default-pretty-printer: false
  # 是否启用 deprecating model converter.
  model-converters.deprecating-converter.enabled: true
  # 生成的Schema等组件的名称是否使用全名(类似java的Class.getName和getSimpleName的区别)
  use-fqn: false # FQN是指 fully qualified names.
  # 是否显示spring security的登录接口
  show-login-endpoint: false
  # 是否预加载OpenAPI文档, true: 程序启动的时候就生成OpenAPI文档, false: 第一次访问OpenAPI文档的时候生成。
  pre-loading-enabled: false

springdoc-openapi-ui同时提供swaggerUI和json API(以及yaml格式)。Springdoc-openapi-webmvc-core只提供swagger API。

SpringBoot + Maven实现多环境动态切换yml配置及配置文件拆分_因特马的博客-CSDN博客_yml 多环境 多功能拆分

踩坑：

参考：

Springboot整合Swagger3全注解配置（springdoc-openapi-ui）_阿祖，收手吧的博客-CSDN博客_springdoc 注解

SpringBoot应用生成RESTful API文档 - Swagger 2.0、OAS 3.0、Springfox、Springdoc、Smart-doc_罗小爬EX的博客-CSDN博客_restfulapi文档生成

文件配置

//swagger访问地址，可以直接访问，会重定向
springdoc.swagger-ui.url = swagger-ui.html
//注意不用单引号包括字符串（踩坑血泪），否则访问时URL也需要加上，要不然一直404
springdoc.group-configs[0].group =就业管理系统
//Swagger只能到包,不能到指定类
springdoc.group-configs[0].packages-to-scan = com.hl.emsystem.controller
//apidoc默认为v3/api-docs,直接访问即可

配置Swagger与SpringDoc

package com.hl.emsystem.config;
 
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import java.util.Collections;
 
/**
 * spring doc配置
 */
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI restfulOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("湖南工业大学就业管理系统")
                        .description("内部Api,版权归HUT所有")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc维基链接")
                        .url("https://springdoc.org/v2"))
                .servers(Collections.singletonList(new Server()
                        .url("http://http://localhost:8081/")
                        .description("就业管理系统对外端口"))
                );
    }
 
}

访问Swagger: localhost:8081/swagger-ui.html

访问api-docs: localhost:8081/v3/api-docs/就业管理系统

使用Apifox自动更新接口

补充说明

在springdoc生态中提供了一个Javadoc模块 - springdoc-openapi-javadoc， 该模块增强了springdoc对Java注释及Tag的处理能力， 但支持有限，目前仅支持：

方法上的注释 - 被解析为@Operation.description（即接口的描述信息，不支持@Operation.summary） @param注释 - 被解析为@Parameter.description（即参数的描述信息） @return注释 - 被解析为@Operation.response.description（即返回结果的描述信息） 对象属性上的注释 - 被解析为@Schema.description

关于注释的解析为api需要额外依赖 therapi-runtime-javadoc

注意: javadoc 只能替换基础功能 特殊功能还需要使用注解实现

关于JavaDoc注释：

Java javadoc 标准和注释规范 - 简书

javadoc注释规范

一、 Java文档

// 注释一行
/ *    */ 注释若干行
/**   ……*/  注释若干行，写入Javadoc文档

二、文档格式

写在类上的文档标注一般分为三段：

第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束 第二段：详细描述， 通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束 第三段：文档标注，用于标注作者，创建时间，参阅类等信息 生成文档是HTML格式。

换行<br>
分段<p>(写在段前）)

示例

/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示，false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
    frame.show(b);
    }

关系图谱

反向链接