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

SpringDoc简介

官方网址 springdoc.org/

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的工具里面

  1. 下载apifox客户端,创建一个项目

  2. 导入数据

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帮助从接口文档维护的重复工作中解放出来,专注与代码的设计。

相关推荐
谙弆悕博士11 小时前
多智能体架构详解:层级树状架构(分级主从型)
运维·架构·大模型·agent·多智能体·langgraph·层级树状
货拉拉技术13 小时前
AI Agent 如何进入实时交易系统:货拉拉的三个实践与一套工程方法论
后端·架构·agent
知白映川14 小时前
一个不上传数据的工具,怎么知道自己有没有人用
安全·架构
谙弆悕博士15 小时前
多智能体架构详解:黑板共享架构(共享存储交互型)
人工智能·架构·大模型·agent·多智能体·黑板架构·anggraph
草莓熊Lotso16 小时前
【C++ 基于微服务的即时通讯系统】ElasticSearch 用户数据管理实现
linux·数据库·c++·elasticsearch·微服务·架构
HelloWorld00116 小时前
Agent 记不住东西?基于分层记忆架构打造 AI Agent 长期记忆与个性化上下文引擎
架构
Keith Guo17 小时前
ESP32-S31芯片架构中文件系统在不同的Flash的位置对PSRAM的性能影响
性能优化·架构·esp32
一条Go18 小时前
SSH 命令审核流:为什么「能执行」必须先「被批准」
后端·架构·github
超低空19 小时前
一文说清LRU算法
后端·算法·架构
AAA修煤气灶刘哥21 小时前
32 GB 内存跑起 1800 亿参数模型,代价是什么?
人工智能·后端·架构