為什么使用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依賴

<!-- 適用于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注解對照表

官方文檔

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