「Spring Boot API 開發：從 0 到 1」Day 15 API 文件自動化

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.6.0'

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.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
<!-- 這裡只列出了和 swagger 相關的 import -->

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Todo List API")
                        .version("1.0")
                        .description("一個簡單但功能強大的待辦事項 API")
                        .contact(new Contact()
                                .name("Cash")
                                .email("[email protected]")))
                .servers(List.of(
                        new Server().url("http://localhost:8080").description("開發環境"),
                        new Server().url("https://api.example.com").description("生產環境")
                ));
    }
}

@RestController
@RequestMapping("/api/todos")
@Tag(name = "Todo", description = "待辦事項管理 API")
public class TodoController {

    @PostMapping
    @Operation(summary = "建立新的待辦事項", description = "建立一個新的待辦事項並將其加入清單中",
    responses = {
            @ApiResponse(responseCode = "200", description = "成功創建待辦事項",
                    content = @Content(schema = @Schema(implementation = ApiResponse.class))),
            @ApiResponse(responseCode = "400", description = "無效的輸入")
    })
    public ResponseEntity<MyApiResponse<Todo>> createTodo(
        @Parameter(description = "待辦事項")
        @RequestBody Todo todo) {
        // 實現邏輯
    }

    @GetMapping
    @Operation(summary = "取得所有待辦事項", description = "取得所有待辦事項的清單")
    public ResponseEntity<MyApiResponse<List<Todo>>> getAllTodos() {
        // 實現邏輯
    }

    // 其他方法類似，可以參考 Github 上 repository 的 commit ...
}

# 這個參數用來設定 Swagger UI 的訪問路徑。預設情況下，Swagger UI 的路徑是 /swagger-ui/index.html
springdoc.swagger-ui.path=/my-custom-swagger-ui

# 這個參數用來設定生成的 OpenAPI 文檔的訪問路徑。預設情況下，這個路徑是 /v3/api-docs
springdoc.api-docs.path=/my-api-docs

# 這個參數用來指定 SpringDoc 應該掃描哪些包來生成 API 文檔。如果不指定，SpringDoc 會掃描所有的包
springdoc.packages-to-scan=com.demo.todolist.controller

# 這個參數用來指定哪些路徑應該包含在生成的 OpenAPI 文檔中。這在你只想要生成特定路徑的 API 文檔時非常有用。
springdoc.paths-to-match=/api/todos/**

# 這個參數用來設定是否在 Swagger UI 中顯示每個 API 請求的持續時間
springdoc.swagger-ui.display-request-duration=true