SpringBoot基于OpenAPI3的接口文档管理快速集成和使用

你好，这里是codetrend专栏“SpringCloud2023实战”。

本文主要简单介绍SpringCloud2023中进行接口文档管理，方便前后端开发和文档维护。文档管理工具基于开源的knife4j封装的openapi3。

前言

OpenAPI 3.0（前身为Swagger）是一种RESTful API文档规范。OpenAPI 3.0规范是一种易于阅读和理解、跨平台和语言、提高协作效率、提供API管理和监控的RESTful API文档规范，提高了API设计和开发的效率、可重用性和互操作性。

有以下几个优点：

易于阅读和理解：OpenAPI 3.0使用简单的YAML或JSON格式，描述了API的所有细节，包括资源路径、HTTP方法、请求参数和响应模型等内容。由于其清晰、结构化的语法，开发人员可以很容易地阅读和理解API文档，快速上手使用API。
自动化工具支持：OpenAPI 3.0规范被广泛支持和使用，有许多自动化工具可以基于OpenAPI规范生成客户端代码、测试用例、API文档和Mock数据等。这些工具能够大大提高开发效率，降低开发成本。
跨平台和语言：OpenAPI 3.0是一种独立于编程语言和平台的规范，可以应用于Java、PHP、Python、Node.js等各种语言和环境中。由于标准化的规范，不同团队或公司之间可以更加容易地进行API的交互和集成，提高了系统的可复用性和互操作性。
提高协作效率：OpenAPI 3.0定义了API的标准接口和参数，避免了开发人员之间因理解不一致而产生的差异。它也为项目经理、测试人员和文档编写者等其他团队提供了清晰的API文档，让他们更快地了解API功能和接口规范，提高协作效率。
提供API管理和监控：OpenAPI 3.0支持API管理和监控的自动化工具集成，例如Swagger UI和Swagger Editor等工具，这些工具可以对API进行实时监控和可视化展示，并提供了许多有用的功能，如在线修改API定义、Mock数据生成和API调试等。

OpenAPI3集成

引入pom.xml

引入OpenAPI主要是引入 springdoc-openapi-starter-webmvc-ui 。
这里使用 knife4j-openapi3-jakarta-spring-boot-starter 快速集成到springboot 3项目，以及使用它提供的增强服务。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><dependencies><!--其他省略--><!-- 引入openapi3接口文档支持 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId></dependency></dependencies></project>

修改配置

新增配置文件 application.yml，配置主要是 springdoc 下面的配置，以及 knife4j 下面的增强实现配置。

spring.application.name: client1
# springdoc-openapi项目配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'packages-to-scan: io.rainforest.banana.client1.web
# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cnbasic:enable: true# Basic认证用户名username: yulin# Basic认证密码password: 123yl.

修改启动类

启动类不需要特殊修改。文档的开启和关闭基于 knife4j.enable控制的。

package io.rainforest.banana.client1;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
}

接口demo

通过访问 http://localhost:10101/client1/swagger-ui.html ，输入账号密码 yulin/123yl. 就可以访问到最新的接口文档。

package io.rainforest.banana.client1.web.demo;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {@Operation(summary = "普通body请求")@PostMapping("/body")public ResponseEntity<String> body(String fileResp){return ResponseEntity.ok(fileResp);}@Operation(summary = "普通body请求+Param+Header+Path")@Parameters({@Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),@Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),@Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)})@PostMapping("/bodyParamHeaderPath/{id}")public ResponseEntity<String> bodyParamHeaderPath(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody String fileResp){return ResponseEntity.ok(fileResp+""+",receiveName:"+name+",token:"+token+",pathID:"+id);}
}

具体的openapi3注释和文档可以查看官方文档。和swagger的语法结构类似，但是注解名称和属性都还是差异很大的。

以下是一个简单的Swagger2和OpenAPI3的注解映射关系，可以参考：

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")