SpringDoc OpenAPI (Swagger)

URL 配置

springdoc:
  api-docs:
    enabled: true 
    path: /api-docs 
  swagger-ui:
    enabled: true 
    path: /swagger-ui.html

Annotations (常用註解)

從 Swagger (SpringFox) 遷移至 SpringDoc OpenAPI

SpringFox 註解	SpringDoc 註解	位置	說明
`@Api(tags = "...")`	`@Tag(name = "...")`	Controller 類別	對 API 進行分組標籤
`@ApiOperation(value = "...")`	`@Operation(summary = "...")`	Controller 方法	描述 API 的功能概要
`@ApiOperation(notes = "...")`	`@Operation(description = "...")`	Controller 方法	提供 API 的詳細描述
`@ApiParam`	`@Parameter`	方法參數	描述參數名稱、是否必填與範例
`@ApiIgnore`	`@Hidden`	類別/方法/參數	在文件中隱藏該元素
`@ApiModel`	`@Schema`	模型類別 (POJO)	描述模型整體定義
`@ApiModelProperty`	`@Schema`	模型欄位	描述屬性含義、限制與範例
`@ApiResponse(code = 200)`	`@ApiResponse(responseCode = "200")`	方法	描述 HTTP 狀態碼與含義
`@RequestParam`	`@Parameter(in = QUERY)`	方法參數	定義查詢參數
`@PathVariable`	`@Parameter(in = PATH)`	方法參數	定義路徑變數

Import 路徑對照

SpringFox (舊)	SpringDoc (新)
`io.swagger.annotations.Api`	`io.swagger.v3.oas.annotations.tags.Tag`
`io.swagger.annotations.ApiOperation`	`io.swagger.v3.oas.annotations.Operation`
`io.swagger.annotations.ApiModel`	`io.swagger.v3.oas.annotations.media.Schema`
`io.swagger.annotations.ApiResponse`	`io.swagger.v3.oas.annotations.responses.ApiResponse`

依賴變更

<!-- 替換舊的 SpringFox 依賴 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.x.x</version>
</dependency>

程式碼範例對比

SpringDoc OpenAPI (新方式)

@Configuration
public class OpenAPIConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文件")
                        .description("詳細描述內容")
                        .version("1.0.0"));
    }
    
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-apis")
                .pathsToMatch("/api/**")
                .build();
    }
}

注意事項 (Notices)

SpringDoc 不需要 @EnableSwagger2 或 @EnableOpenApi 註解。
Swagger UI 預設路徑可能從 /swagger-ui.html 變更為 /swagger-ui/index.html。
API 文件 JSON 路徑從 /v2/api-docs 變更為 /v3/api-docs。

Spring Scheduling Thymeleaf