系列文章：
springboot-swagger詳解
springboot-優美的Knife4j文檔-Swagger進化
Spring Cloud Gateway 網關整合 Knife4j
SpringBoot之如何集成SpringDoc最詳細文檔

一、概念解釋

Swagger和Springdoc是兩個常用的工具，用于生成和維護API文檔，特別是針對基于REST的Web服務。它們有效地提升了API的可讀性和可維護性，幫助開發者、產品經理和其他利益相關者更好地理解和使用所提供的API。

談到API文檔，那就繞不開大名鼎鼎的Swagger，但是你是否還聽說過：OpenAPI，Springfox，Springdoc？你第一次看到這些腦瓜子是不是嗡嗡的？

1、OpenAPI

OpenApi 就像 JDBC 一樣，制定了各種各樣的規范，而 Swagger 和 SpringDoc 則類似于各種各樣的數據庫驅動，是具體的實現

• 定義 ：OpenAPI 是一個開放標準，用于描述 RESTful API 的接口規范。它最初由 Swagger 項目發展而來，后來成為獨立的標準（目前由 OpenAPI Initiative 維護）。

• 版本 ：

  • OpenAPI 2.0 ：基于 Swagger 2.0 規范。
  • OpenAPI 3.0+ ：是更新的版本，引入了許多新特性（如增強的請求體描述、組件復用等）。

• 作用 ：提供一種標準化的方式來描述 API 的結構、路徑、參數、響應等內容，便于開發者和工具生成文檔、測試接口。

2、Swagger

它是SmartBear這個公司的一個開源項目，里面提供了一系列工具，包括著名的 swagger-ui。
swagger是早于OpenApi的，某一天swagger將自己的API設計貢獻給了OpenApi，然后由其標準化了。

• 定義 ：Swagger 是一組圍繞 OpenAPI 標準構建的工具集，包括代碼生成器、UI 展示工具等。
• 版本 ：
  • Swagger 2.x ：基于 OpenAPI 2.0，是最廣泛使用的版本之一。
  • Swagger 3.x ：基于 OpenAPI 3.0+，支持更復雜的 API 描述功能。
• 工具 ：
  • Swagger UI ：為 OpenAPI 文檔提供交互式界面，方便開發者測試 API。
  • Swagger Codegen ：根據 OpenAPI 文檔生成客戶端代碼或服務器端框架代碼。

3、Springfox

是Spring生態的一個開源庫，是Swagger與OpenApi規范的具體實現。我們使用它就可以在spring中生成API文檔。以前基本上是行業標準，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三種格式。但是其從 2020年7月14號就不再更新了，不支持springboot3，所以業界都在不斷的轉向我們今天要談論的另一個庫Springdoc，新項目就不要用了。

• 定義 ：Springfox 是一個專門為 Spring 框架設計的庫，用于自動生成基于 Swagger/OpenAPI 的 API 文檔。
• 特點 ：
  • 支持 Spring MVC 和 Spring Boot。
  • 主要基于 Swagger 2.x 和 OpenAPI 2.0 。
  • 通過注解（如 @Api、@ApiOperation 等）來描述 API。
• 局限性 ：
  • 對 OpenAPI 3.0 的支持較弱（盡管有實驗性支持，但不夠完善）。
  • 在 Spring Boot 2.6 及更高版本中，由于兼容性問題（如路徑匹配策略的變化），Springfox 的使用變得復雜甚至不可行。

4、Springdoc

算是后起之秀，帶著繼任Springfox的使命而來。其支持OpenApi規范，支持Springboot3，我們的新項目都應該使用這個。

• 定義 ：Springdoc 是一個現代化的開源庫，專為 Spring Boot 應用程序設計，用于自動生成基于 OpenAPI 3.0+ 的 API 文檔。
• 特點 ：
  • 原生支持 OpenAPI 3.0+ ，并提供對 Spring Boot 2.6+ 的良好兼容性。
  • 使用標準的 OpenAPI 注解（如 @Operation、@Parameter 等），而不是 Swagger 特有的注解。
  • 提供內置的 Swagger UI，方便開發者快速查看和測試 API。
• 優勢 ：
  • 更輕量、更易配置。
  • 更好的性能和兼容性。
  • 社區活躍，更新頻繁。

SpringDoc 支持：

• OpenAPI 3
• Spring-boot，全版本都支持。
• JSR-303 中提供的一些注解，例如 @NotNull、@Min、@Max 以及 @Size 等。
• Swagger-ui：SpringDoc 提供的接口 JSON 也可以通過 Swagger-ui 展示出來。
• OAuth 2
• …

5. 關系與區別

特性	Springfox	Springdoc	Swagger	OpenAPI
主要用途	自動生成 API 文檔	自動生成 API 文檔	工具集，用于生成文檔和測試 API	API 描述標準
支持的規范	Swagger 2.x / OpenAPI 2.0	OpenAPI 3.0+	Swagger 2.x / Swagger 3.x	OpenAPI 2.0 / OpenAPI 3.0+
Spring Boot 兼容性	較差（尤其是 2.6+ 版本）	良好	不直接相關	不直接相關
注解	使用 Swagger 特定注解（如 @Api）	使用 OpenAPI 標準注解（如 @Operation）	使用 Swagger 特定注解	定義了標準注解
工具支持	提供 Swagger UI	提供 Swagger UI	提供 Swagger UI 和 Codegen	無直接工具支持，需依賴實現（如 Swagger）
社區活躍度	逐漸減少	高	高	高

二、SpringDoc基本使用

我們可以在springboot中使用SpringDoc來生成API文檔，詳情可以參考官網，下面我們來簡單的實踐一下。

1、導包

在springboot中使用springdoc起步非常容易，只需要引入其starter即可

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.7.0</version> <!-- 版本可替換 -->
</dependency>

2、正常編寫代碼，不需要任何注解

3、運行后訪問下面的鏈接即可

http://server:port/context-path/swagger-ui.html

例如：

http://localhost:9204/swagger-ui.html

三、SpringDoc進階使用

雖然上邊配置的SpringDoc很好用，但是對比swagger我們就知道，缺少了很多信息，當然springdoc的集成不可能就這點東西，不然也沒有這篇文章了。

1、配置文檔信息

得益于springboot的強大，我們只需添加一個依賴就可以使用API文檔了，但是使用的都是默認值，我們當然也希望對其進行各種自定義的配置

創建一個OpenAPI 的bean，配置文檔名稱等信息

package com.wenge.business.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** Swagger 文檔配置** @author wkl*/
@Configuration
public class SpringDocAutoConfiguration {@Beanpublic OpenAPI openApi() {return new OpenAPI().info(new Info().title("這是標題").description("這是備注").version("這是版本").license(new License().name("這是許可證").url("這是許可證鏈接")).contact(new Contact().name("這是作者").url("這是作者鏈接").email("這是作者email")));}
}

2、配置文檔分組

用來配置分組的，假如你有多類controller一類以/tacticsInfo為前綴分組，一類以/admin為前綴，就可以將其配置為兩個分組。很多時候我們只有一個分組，所以就不需要下面的配置。

    @Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("tacticsInfo").pathsToMatch("/tacticsInfo/**")//以/tacticsInfo開頭的的api都進這個分組.build();}@Beanpublic GroupedOpenApi otherApi() {return GroupedOpenApi.builder().group("other").pathsToMatch("/admin/**")//以/tacticsInfo開頭的的api都進這個分組.build();}//    @Bean
//    public GroupedOpenApi otherApi() {
//        return GroupedOpenApi.builder()
//                .group("other")
//                .pathsToMatch("/**/**")//這樣配置，那就是所有的api都進這個分組
//                .build();
//    }

可以通過右上角的下拉框選擇要展示的group。

3、springdoc的配置參數

1. 基礎配置

API 文檔路徑-springdoc.api-docs.path

• springdoc.api-docs.path
  • 作用：指定 OpenAPI JSON 文檔的訪問路徑。
  • 默認值：/v3/api-docs
  • 示例：

    springdoc.api-docs.path=/openapi
    

Swagger UI 路徑-springdoc.swagger-ui.path

• springdoc.swagger-ui.path
  • 作用：指定 Swagger UI 的訪問路徑。
  • 默認值：/swagger-ui.html
  • 示例：

    springdoc.swagger-ui.path=/docs
    

是否啟用 API 文檔-springdoc.api-docs.enabled

• springdoc.api-docs.enabled
  • 作用：啟用或禁用 OpenAPI 文檔生成功能。
  • 默認值：true
  • 示例：

    springdoc.api-docs.enabled=false
    

是否啟用 Swagger UI-springdoc.swagger-ui.enabled

• springdoc.swagger-ui.enabled
  • 作用：啟用或禁用 Swagger UI。
  • 默認值：true
  • 示例：

    springdoc.swagger-ui.enabled=false
    

---

2. 全局元信息-info

應用標題-springdoc.info.title

• springdoc.info.title
  • 作用：設置 API 文檔的標題。
  • 默認值：空
  • 示例：

    springdoc.info.title=用戶管理系統
    

應用描述-springdoc.info.description

• springdoc.info.description
  • 作用：設置 API 文檔的描述信息。
  • 默認值：空
  • 示例：

    springdoc.info.description=用戶管理相關的 API 文檔
    

版本號-pringdoc.info.version

• springdoc.info.version
  • 作用：設置 API 文檔的版本號。
  • 默認值：空
  • 示例：

    springdoc.info.version=1.0.0
    

聯系人信息-springdoc.info.contact

• springdoc.info.contact.name
• springdoc.info.contact.email
• springdoc.info.contact.url
  • 作用：設置文檔的聯系人信息（姓名、郵箱、URL）。
  • 默認值：空
  • 示例：

    springdoc.info.contact.name=John Doe
    springdoc.info.contact.email=john.doe@example.com
    springdoc.info.contact.url=http://example.com
    

許可信息-pringdoc.info.license

• springdoc.info.license.name
• springdoc.info.license.url
  • 作用：設置文檔的許可證信息（名稱、URL）。
  • 默認值：空
  • 示例：

    springdoc.info.license.name=Apache 2.0
    springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0
    

---

3. 分組與模塊化

分組支持-springdoc.group-configs

• springdoc.group-configs
  • 作用：為不同的控制器或包生成獨立的 API 文檔分組。
  • 示例：

    springdoc.group-configs[0].group=user-api
    springdoc.group-configs[0].packages-to-scan=com.example.user
    springdoc.group-configs[1].group=order-api
    springdoc.group-configs[1].packages-to-scan=com.example.order
    

掃描包范圍-springdoc.packages-to-scan

• springdoc.packages-to-scan
  • 作用：指定需要掃描的包范圍，用于生成 API 文檔。
  • 默認值：當前應用程序的所有包。
  • 示例：

    springdoc.packages-to-scan=com.example.api
    

排除特定路徑-springdoc.paths-to-exclude

• springdoc.paths-to-exclude
  • 作用：排除某些路徑，不將其包含在生成的 API 文檔中。
  • 默認值：無
  • 示例：

    springdoc.paths-to-exclude=/admin/**
    

---

4. 安全配置

全局安全方案

• springdoc.api-docs.security-schemes
  • 作用：定義全局的安全方案（如 OAuth2、API Key 等）。
  • 示例：

    springdoc.api-docs.security-schemes[0].name=ApiKeyAuth
    springdoc.api-docs.security-schemes[0].type=apiKey
    springdoc.api-docs.security-schemes[0].in=header
    

全局安全要求

• springdoc.api-docs.security-requirements
  • 作用：定義全局的安全要求。
  • 示例：

    springdoc.api-docs.security-requirements[0]=ApiKeyAuth
    

---

5. 自定義行為

緩存控制

• springdoc.cache.disabled
  • 作用：禁用 API 文檔的緩存。
  • 默認值：false
  • 示例：

    springdoc.cache.disabled=true
    

排序規則

• springdoc.default-flat-param-object
  • 作用：是否將參數對象展平為單個參數。
  • 默認值：false
  • 示例：

    springdoc.default-flat-param-object=true
    

服務器地址-pringdoc.servers

• springdoc.servers
  • 作用：定義 API 的服務器地址列表。
  • 示例：

    springdoc.servers[0].url=http://localhost:8080
    springdoc.servers[0].description=本地開發環境
    springdoc.servers[1].url=https://api.example.com
    springdoc.servers[1].description=生產環境
    

---

6. 高級配置

自定義 OpenAPI 對象

• 作用：通過 Java 配置類自定義 OpenAPI 對象。
• 示例：

  @Bean
  public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("用戶管理系統").version("1.0").description("用戶管理相關的 API 文檔")).addServersItem(new Server().url("http://localhost:8080").description("本地開發環境"));
  }
  

自定義 Swagger UI

• 作用：通過 Java 配置類自定義 Swagger UI 行為。
• 示例：

  @Bean
  public SwaggerUiConfigProperties swaggerUiConfig() {SwaggerUiConfigProperties config = new SwaggerUiConfigProperties();config.setPath("/custom-docs");return config;
  }
  

---

7. 總結

以下是 springdoc 配置參數的分類總結：

類別	參數	作用
基礎配置	springdoc.api-docs.path, springdoc.swagger-ui.path, springdoc.api-docs.enabled	配置 API 文檔路徑、Swagger UI 路徑及啟用狀態。
全局元信息	springdoc.info.title, springdoc.info.description, springdoc.info.version	設置 API 文檔的標題、描述、版本等基本信息。
分組與模塊化	springdoc.group-configs, springdoc.packages-to-scan, springdoc.paths-to-exclude	支持分組、限制掃描范圍、排除特定路徑。
安全配置	springdoc.api-docs.security-schemes, springdoc.api-docs.security-requirements	定義全局安全方案和要求。
自定義行為	springdoc.cache.disabled, springdoc.default-flat-param-object, springdoc.servers	控制緩存、參數對象展平、服務器地址等高級功能。
高級配置	自定義 OpenAPI 對象、Swagger UI 配置	通過代碼方式實現更靈活的定制。

4、SpringDoc注解

1. 核心注解

@Tag

• 作用：為控制器或方法分組，便于組織和分類 API。

• 常用屬性：

  • name：標簽名稱。
  • description：標簽描述信息。

• 示例：

    @Tag(name = "策略庫接口",description = "這是策略庫的所有接口")@RestController@RequestMapping("/tacticsInfo")public class TacticsInfoController extends BaseController{// ...}
  

---

2. 方法級別注解

@Operation

• 作用：描述一個 API 方法的功能。
• 常用屬性：
  • summary：方法的簡短描述。
  • description：方法的詳細描述。
  • responses：定義可能的響應結果。
  • deprecated：標記方法是否已廢棄。
• 示例：

    @Operation(summary = "查詢策略庫:tactics_info列表",description = "查詢策略庫:tactics_info列表-list接口")@RequiresPermissions("business:tacticsInfo:list")@GetMapping("/list")public TableDataInfo list(TacticsInfo tacticsInfo){// ...
  }
  

@ApiResponse 和 @ApiResponses

• 作用：描述 API 方法的響應結果。
• 常用屬性：
  • responseCode：HTTP 狀態碼。
  • description：響應描述信息。
  • content：響應的內容類型（如 JSON、XML）。
• 示例：

  @Operation(summary = "創建用戶", description = "根據用戶信息創建新用戶")
  @ApiResponses({@ApiResponse(responseCode = "200", description = "成功創建用戶"),@ApiResponse(responseCode = "400", description = "請求參數錯誤"),@ApiResponse(responseCode = "500", description = "服務器內部錯誤")
  })
  @PostMapping
  public ResponseEntity<User> createUser(@RequestBody User user) {// ...
  }
  

---

3. 參數相關注解

@Parameter

• 作用：描述方法參數的含義。
• 常用屬性：
  • name：參數名稱。
  • description：參數描述信息。
  • required：是否必填。
  • example：參數示例值。
  • in：參數位置（如 path、query、header 等）。
• 示例：

  @Operation(summary = "根據 ID 獲取用戶")
  @GetMapping("/{id}")
  public User getUserById(@Parameter(name = "id", description = "用戶 ID", required = true, example = "1") @PathVariable Long id) {// ...
  }
  

@Parameters

• 作用：描述多個參數。
• 示例：

  @Operation(summary = "搜索用戶")
  @Parameters({@Parameter(name = "name", description = "用戶名", in = ParameterIn.QUERY),@Parameter(name = "age", description = "用戶年齡", in = ParameterIn.QUERY)
  })
  @GetMapping("/search")
  public List<User> searchUsers(@RequestParam String name, @RequestParam Integer age) {// ...
  }
  

---

4. 實體模型相關注解

@Schema

• 作用：描述實體類或字段的信息。
• 常用屬性：
  • description：模型或字段的描述信息。
  • example：字段示例值。
  • required：字段是否必填。
  • type：字段的數據類型。
  • format：字段的格式（如 date-time、email 等）。
• 示例：

  @Schema(description = "用戶的基本信息")
  public class User {@Schema(description = "用戶 ID", example = "1", required = true)private Long id;@Schema(description = "用戶名", example = "John Doe", required = true)private String name;@Schema(description = "用戶年齡", example = "25")private Integer age;// getters and setters
  }
  

---

5. 其他注解

@Hidden

• 作用：隱藏某個類、方法或參數，不將其包含在生成的文檔中。
• 示例：

  @Hidden
  @GetMapping("/internal")
  public String internalEndpoint() {return "This endpoint is ignored by springdoc.";
  }
  

---

6. 配置相關注解（不常用）

@OpenAPIDefinition

• 作用：全局配置 OpenAPI 文檔的元信息。這個不常用，還是常用配置文件類型的
• 常用屬性：
  • info：文檔的基本信息（標題、版本、描述等）。
  • tags：全局標簽定義。
  • servers：API 的服務器地址。
• 示例：

  @OpenAPIDefinition(info = @Info(title = "用戶管理系統", version = "1.0", description = "用戶相關的 API 文檔"),tags = {@Tag(name = "用戶管理", description = "與用戶相關的操作")},servers = {@Server(url = "http://localhost:8080", description = "本地開發環境")}
  )
  @SpringBootApplication
  public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
  }
  

---

7. 總結

以下是 springdoc 常用注解的分類總結：

注解	作用
@Tag	為控制器或方法分組，便于組織和分類 API。
@Operation	描述 API 方法的功能。
@ApiResponse	描述單個響應結果。
@Parameter	描述方法參數的含義。
@Schema	描述實體類或字段的信息。
@Hidden	隱藏某個類、方法或參數，不包含在生成的文檔中。
@OpenAPIDefinition	全局配置 OpenAPI 文檔的元信息（標題、版本、描述等）。

四、在實際項目上如何使用

1、導包

在springboot中使用springdoc起步非常容易，只需要引入其starter即可

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.7.0</version> <!-- 版本可替換 -->
</dependency>

2、寫配置類

1）、配置實體類

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.NestedConfigurationProperty;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;/*** Swagger 配置屬性** @author wkl*/
@ConfigurationProperties(prefix = "springdoc")
public class SpringDocProperties
{/*** 網關*/private String gatewayUrl;/*** 文檔基本信息*/@NestedConfigurationPropertyprivate InfoProperties info = new InfoProperties();/*** <p>* 文檔的基礎屬性信息* </p>** @see io.swagger.v3.oas.models.info.Info** 為了 springboot 自動生產配置提示信息，所以這里復制一個類出來*/public static class InfoProperties{/*** 標題*/private String title = null;/*** 描述*/private String description = null;/*** 聯系人信息*/@NestedConfigurationPropertyprivate Contact contact = null;/*** 許可證*/@NestedConfigurationPropertyprivate License license = null;/*** 版本*/private String version = null;public String getTitle(){return title;}public void setTitle(String title){this.title = title;}public String getDescription(){return description;}public void setDescription(String description){this.description = description;}public Contact getContact(){return contact;}public void setContact(Contact contact){this.contact = contact;}public License getLicense(){return license;}public void setLicense(License license){this.license = license;}public String getVersion(){return version;}public void setVersion(String version){this.version = version;}}public String getGatewayUrl(){return gatewayUrl;}public void setGatewayUrl(String gatewayUrl){this.gatewayUrl = gatewayUrl;}public InfoProperties getInfo(){return info;}public void setInfo(InfoProperties info){this.info = info;}
}

2）、配置類

import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import com.wenge.common.swagger.config.properties.SpringDocProperties;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.servers.Server;/*** Swagger 文檔配置** @author ruoyi*/
@EnableConfigurationProperties(SpringDocProperties.class)
@ConditionalOnProperty(name = "springdoc.api-docs.enabled", havingValue = "true", matchIfMissing = true)
public class SpringDocAutoConfiguration
{@Bean@ConditionalOnMissingBean(OpenAPI.class)public OpenAPI openApi(SpringDocProperties properties){return new OpenAPI().components(new Components()// 設置認證的請求頭.addSecuritySchemes("apikey", securityScheme())).addSecurityItem(new SecurityRequirement().addList("apikey")).info(convertInfo(properties.getInfo())).servers(servers(properties.getGatewayUrl()));}public SecurityScheme securityScheme(){return new SecurityScheme().type(SecurityScheme.Type.APIKEY).name("Authorization").in(SecurityScheme.In.HEADER).scheme("Bearer");}private Info convertInfo(SpringDocProperties.InfoProperties infoProperties){Info info = new Info();info.setTitle(infoProperties.getTitle());info.setDescription(infoProperties.getDescription());info.setContact(infoProperties.getContact());info.setLicense(infoProperties.getLicense());info.setVersion(infoProperties.getVersion());return info;}public List<Server> servers(String gatewayUrl){List<Server> serverList = new ArrayList<>();serverList.add(new Server().url(gatewayUrl));return serverList;}
}

3、編寫配置參數

springdoc:api-docs:path: /v3/api-docsswagger-ui:path: /swagger-ui.htmlenabled: trueoperationsSorter: methodshow-actuator: true