在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全系列都支持的。

欢迎关注公众号：SpringForAll社区（spring4all.com），专注分享关于Spring的一切！回复“加群”还可加入Spring技术交流群！

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

文档地址：https://springdoc.org/#getting-started

1. 创建SpringBoot项目

2. 引入SpringDoc依赖

    

     
<!-- 适用于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依赖，无需引入其它依赖即可生效。

3. 创建一个测试接口，添加SpringDoc的注解以生成在线文档

    

     
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;
     
}
     
    
     
}
    

4. 启动项目后访问提供的接口地址

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

效果图如下

Springfox和SpringDoc注解对照表

官方文档：https://springdoc.org/index.html#migrating-from-springfox

作者：叹雪飞花
链接：https://juejin.cn/post/7302041173866119194

给大家推荐我们团队开发的Chrome插件：YouTube中文配音（https://www.youtube-dubbing.com/）。如果您跟我们一样，热爱看国外的视频学习前沿知识或者其他内容，该插件可以很好的帮助您讲外语视频一键转化为中文视频！

END