SpringBoot集成SpringDoc生成标准的OpenAPI接口文档实践

SpringDoc简介

SpringDoc 是一个开源项目，用于自动化生成和维护 Spring Boot 应用程序的 OpenAPI 3 规范文档。OpenAPI（以前称为Swagger）是一个规范和完整的框架，用于描述、生产、消费和可视化 RESTful Web 服务的API。SpringDoc 利用 OpenAPI 3 规范，为开发者提供了一种简便的方式来生成和展示他们的 API 文档。

概览

基本概念

名词概念	说明
OpenAPI	是一个组织（OpenAPI Initiative），他们指定了一个如何描述HTTP API的规范（OpenAPI Specification）。既然是规范，那么谁想实现都可以，只要符合规范即可。
Swagger	它是SmartBear这个公司的一个开源项目，里面提供了一系列工具，包括著名的 swagger-ui。swagger是早于OpenApi的，某一天swagger将自己的API设计贡献给了OpenApi，然后由其标准化了。
Springfox	是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了，不支持springboot3，所以业界都在不断的转向我们今天要谈论的另一个库Springdoc，新项目就不要用了。
SpringDoc	SpringDoc是Spring官方推荐的API，支持SpringBoot3, 简化了Rest API 接口文档生成和维护的复杂度

SpringBoot集成SpringDoc

1. 安装依赖

对于spring-boot 和 swagger-ui集成SpringDoc直接安装依赖，不需要其他的任何配置。

xml 复制代码

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>2.3.0</version>
   </dependency>

2、查看api接口信息

项目启动之后，直接访问 http://localhost:8080/v3/api-docs 即可，注意端口号是项目启动的端口号

3、导入文档工具

SpringDoc支持openapi规范，所以市面上大部分框架均支持导入。例如: apifox apipost postman torna knife4j 等，根据对应工具的文档接入即可

下面以ruoyi-vue-plus项目为例导入到apifox的工具里面

下载apifox客户端，创建一个项目
导入数据

Swagger升级SpringDoc指南

swagger	springdoc	javadoc
@Api(name = "xxx")	@Tag(name = "xxx")	java类注释第一行
@Api(description= "xxx")	@Tag(description= "xxx")	java类注释
@ApiOperation	@Operation	java方法注释
@ApiIgnore	@Hidden	无
@ApiParam	@Parameter	java方法@param参数注释
@ApiImplicitParam	@Parameter	java方法@param参数注释
@ApiImplicitParams	@Parameters	多个@param参数注释
@ApiModel	@Schema	java实体类注释
@ApiModelProperty	@Schema	java属性注释
@ApiModelProperty(hidden = true)	@Schema(accessMode = READ_ONLY)	无
@ApiResponse	@ApiResponse	java方法@return返回值注释

总结

接口文档维护和更新对于小的快速迭代的项目非常重要，如传统的rap接口管理的文档，定义接口然后进行开发，代码接口变更的时候接口文档没有维护导致偏差。spring doc帮助从接口文档维护的重复工作中解放出来，专注与代码的设计。