SpringBoot3.x最简集成SpringDoc-OpenApi

为什么使用SpringDoc

在SpringBoot低版本时一般使用Swagger扫描接口生成Json格式的在线文档,然后通过swagger-ui将Json格式的文档以页面形式展示文档。可惜遗憾的是swagger更新到3.0.0版本(springfox)后不更新了。

SpringBoot3.x以后需要的JDK版本最低为Java17,而Java17的包名在之前的版本中从javax更改为jakarta,导致swagger在SpringBoot3.x版本中完全无法使用,而SpringDoc不同于swagger,在SpringBoot出了3版本以后很快就兼容升级了,换句话说SpringDoc是SpringBoot全系列都支持的。

SpringDoc支持的内容

  • OpenAPI 3的标准实现
  • Spring-boot v3 (Java 17 & Jakarta EE 9)
  • JSR-303支持, 专门针对 @NotNull, @Min, @Max, and @Size.
  • Swagger-ui支持
  • OAuth2 认证流程
  • 本机镜像打包支持(GraalVM native images)

最简集成SpringDoc

文档地址

  1. 创建SpringBoot项目
  2. 引入SpringDoc依赖
xml 复制代码
<!-- 适用于webmvc的SpringDoc依赖 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.2.0</version>
</dependency>

该依赖包含swagger-ui和springdoc-openapi-starter-webmvc-api依赖,无需引入其它依赖即可生效。

  1. 创建一个测试接口,添加SpringDoc的注解以生成在线文档
java 复制代码
package com.example.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 示例接口
 *
 * @author vains
 */
@RestController
@RequestMapping("/example")
@Tag(name = "示例接口", description = "提供示例内容展示SpringDoc集成效果")
public class ExampleController {

    @GetMapping("/test01")
    @Operation(summary = "无参查询接口", description = "hello")
    public String test01() {
        return "Hello Spring doc";
    }

    @GetMapping("/test02")
    @Parameter(name = "test02", description = "url参数")
    @Operation(summary = "查询参数示例", description = "原样返回入参")
    public String test02(String test02) {
        return test02;
    }

    @GetMapping("/test03/{test03}")
    @Parameter(name = "test03", description = "url参数")
    @Operation(summary = "url参数示例", description = "原样返回入参")
    public String test03(@PathVariable String test03) {
        return test03;
    }
    
}
  1. 启动项目后访问提供的接口地址

http://127.0.0.1:8080/swagger-ui/index.html

效果图如下

Springfox和SpringDoc注解对照表

官方文档

Springfox SpringDoc 解释说明
@Api @Tag 描述接口信息
@ApiIgnore @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @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") 描述接口响应信息,包括状态码和消息

附录

  1. SpringDoc官网
  2. 代码仓库:Gitee、Github
相关推荐
特立独行的猫A5 小时前
别再用 nohup 了:让应用在后台常驻的正确姿势与 systemd 服务详解
java·后端·python
一起_java5 小时前
技术文章-基于Dify-Agent的智能问答系统设计与实现
java·spring boot·后端·agent·dify
码事漫谈6 小时前
2027年火的很可能是AI工作台
后端
Flynn Liang6 小时前
I/O 密集型高并发实战:Java 服务 10 维优化,从线程打满到 10 万 QPS
java·spring boot·性能优化·高并发·系统设计·虚拟线程·io密集型
吃我一窝jio7 小时前
Python与Go线程模型深度对比
java·开发语言·python
这个昵称不容易8 小时前
SpringBoot 购物推荐网站的设计与实现:120 个 Java 文件、147 个接口、13 张表,附真实运行截图
java·springboot·毕设
文丑颜不良啊8 小时前
LeetCode3041~3060题目解析
java·leetcode
文丑颜不良啊9 小时前
LeetCode3101~3120题目解析
java·leetcode
Resean02239 小时前
SpringMVC 6+源码分析(十一)视图渲染与异步请求(收尾篇)
java·spring·springmvc
starzy199010 小时前
深入理解Scala隐式函数:自动类型转换
开发语言·后端·scala