擁抱 OpenAPI 3：springdoc-openapi 食用指南

小二十七發表於2022-06-16
APISpring

概述

使用 springdoc-openapi 可以快速為 springboot 專案生成規範的 API 文件，具體使用步驟如下：

依賴配置

在 pom.xml 加入內容，即可開始使用：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

然後在 Config 中配置基本的描述資訊，如下：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("SpringDoc API Test")
                        .description("SpringDoc Simple Application Test")
                        .version("0.0.1"));
    }

}

接下來在 Controller 中使用註解標記文字，如下：

@RestController(value = "/clients")
@Tag(name = "/clients")
public class ClientsRestController {

    @Operation(summary = "This method is used to get the clients.")
    @GetMapping
    public List<String> getClients() {
        return Arrays.asList("First Client", "Second Client");
    }
}

最後 Application.java 啟動應用後，輸入預設地址：http://localhost:8081/swagger-ui/index.html 即可看到文件：

image-20220616224457245

在地址 http://localhost:8081/v3/api-docs 目錄中，openAPI 3.0.1 檔案，格式如下：

image-20220616224628270

總結

很多從 swagger 2 過來的使用者可能會好奇，為什麼不使用 springfox 庫來生成 API，我在這裡簡單總結一下

推薦使用 springdoc-openapi 的理由如下：

  • springdoc-openapi 是 spring 官方出品，與 springboot 相容更好（springfox 相容有坑）
  • springdoc-openapi 社群更活躍，springfox 已經 2 年沒更新了
  • springdoc-openapi 的註解更接近 OpenAPI 3 規範

綜上所述，我個人還是更加推薦使用 springdoc-openapi 來自動化你專案的 API 文件

相關文章