【Day - 16】深入了解 SpringDoc OpenAPI：自動生成精美的 API 文件 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2023 iThome 鐵人賽

DAY 16

Mobile Development

Spring Boot+Android 30天實戰開發系列第 16 篇

【Day - 16】深入了解 SpringDoc OpenAPI：自動生成精美的 API 文件

15th鐵人賽 spring boot spring security

ian_liu

團隊nutc_imac_FewFew

2023-09-26 10:09:35

3765 瀏覽

分享至

1. 引言

API 文件在現代軟體開發中扮演著至關重要的角色。它們不僅提供了關於你的應用程式如何運作的清晰說明，還可以幫助其他開發者更容易地理解、使用和整合你的服務。然而，手動創建和維護 API 文件往往是一項繁瑣且容易出錯的任務。

本文將介紹 SpringDoc OpenAPI，這是一個強大的工具，可以自動生成精美的 API 文件，從而簡化了這一任務。無論是初學者還是經驗豐富的開發者，都能受益於 SpringDoc OpenAPI 帶來的便利性和效率。

在本文中，我們將深入探討 SpringDoc OpenAPI 的功能和用途，並提供實際的示例來演示如何在 Spring Boot 項目中使用它。接下來，讓我們開始了解 SpringDoc OpenAPI 的基礎知識。

2. 2. SpringDoc OpenAPI 簡介

2.1 什麼是 SpringDoc OpenAPI？

SpringDoc OpenAPI 是一個用於自動生成 API 文件的工具，特別針對 Spring Boot 項目進行了優化。它基於 OpenAPI 3.0 規範，旨在簡化 API 文件的生成過程，同時提供了豐富的客製化和擴展功能。

2.2 SpringDoc OpenAPI 的主要目標

SpringDoc OpenAPI 的主要目標是幫助開發者自動生成符合 OpenAPI 3.0 規範的 API 文件。它實現了以下目標：

減少手動編寫文件的工作量：開發者無需花費大量時間來手動編寫 API 文件，而是讓工具自動處理這一任務。
提高文件的一致性：生成的文件符合標準，並保持一致性，這有助於其他開發者更容易理解和使用你的 API。
提供客製化和擴展功能：SpringDoc OpenAPI 允許你根據項目的需要進行客製化，包括添加自定義描述、分組和標籤等。
整合 Spring Boot：它與 Spring Boot 無縫集成，可以輕鬆將其添加到現有的 Spring Boot 項目中。

SpringDoc OpenAPI 的功能豐富，可以滿足各種 API 文件生成的需求。接下來，我們將深入探討如何開始使用 SpringDoc OpenAPI，並示範它的一些基本功能。

3. 開始使用 SpringDoc OpenAPI

現在，讓我們開始探討如何在你的 Spring Boot 項目中使用 SpringDoc OpenAPI 來自動生成 API 文件。這個過程相對簡單，只需要一些基本的配置步驟。

添加 SpringDoc OpenAPI 依賴

首先，你需要添加相關的依賴。在你的專案的 Maven pom.xml文件中，添加以下依賴：

<dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.0.2</version>
</dependency>

這個依賴包含了 SpringDoc OpenAPI 的核心功能，以及一個用於 Web MVC 框架的 UI 界面，讓你可以輕鬆查看生成的 API 文件。

步驟 2: 配置 SpringDoc OpenAPI

一旦你添加了依賴，你需要配置 SpringDoc OpenAPI。通常，這可以在你的 Spring Boot 配置文件（如 application.properties 或 application.yml）中完成。以下是一個示例配置：

# 配置 SpringDoc OpenAPI
springdoc:
  api-docs:
    enabled: true # 預設的
    path: /api-docs # API 文件的路徑，預設的
  swagger-ui:
    enabled: true # 預設的
    path: /swagger-ui.html # Swagger UI 界面的路徑，預設的

步驟 3: 創建配置類：用於配置API文件基本信息

為了配置 API 文件的基本信息，你需要定義一個配置類，例如 SpringDocConfig，並使用 @OpenAPIDefinition 和 @Configuration 註解來標記。這個配置類應該包含一個 @Bean 方法，用於定義 OpenAPI 物件，並設置 API 的標題、版本等基本信息。以下是一個示例配置：

@OpenAPIDefinition
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI baseOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Ironman2023 API Documentation - 2023 IT鐵人賽範例")
                        .description("SpringBoot 3.x application")
                        .version("v0.0.1")
                        .license(new License().name("Your License").url("http://springdoc.org"))
                        .contact(new Contact().name("Ian Liu").email("ianliu@example.com").url("Your Website URl"))
                );
    }
}

在這個配置類中，我們使用了 OpenAPI 物件來定義 API 的基本信息，包括標題、描述、版本、許可證、聯繫人等。你可以根據你的項目需求自定義這些信息。

步驟 4: 訪問 API 文件

現在，你可以啟動你的 Spring Boot 應用程式。當應用程式啟動時，SpringDoc OpenAPI 會自動掃描你的控制器類，生成 API 文件並提供 Swagger UI 界面。

一旦你的應用程式運行，你可以通過訪問以下 URL 來查看生成的 API 文件和 Swagger UI：

API 文件：http://localhost:8080/api-docs（根據你的應用程式端口和路徑進行調整）
Swagger UI：http://localhost:8080/swagger-ui.html（同樣，根據你的應用程式端口和路徑進行調整）

4. 記錄 Spring Boot REST API

在這一節中，我們將使用一個簡單的範例來示範如何使用 SpringDoc OpenAPI 記錄 Spring Boot REST API。我們將建立一個管理書籍信息的 API，包括以下端點：

GET /books：檢索所有書籍。
GET /books/{id}：按 ID 檢索單個書籍。
POST /books：創建一本新書。
PUT /books/{id}：按 ID 更新一本書。
DELETE /books/{id}：按 ID 刪除一本書。

4.1 記錄 Controller

我們將創建一個簡單的書籍管理控制器（BookController），並使用 SpringDoc OpenAPI 註解來記錄這些 API 端點。以下是示例的控制器程式碼：

@RestController
@RequestMapping("/books")
@Tag(name = "Book API", description = "Operations for managing books")
public class BookController {

    @GetMapping
    @Operation(summary = "Get all books", description = "Retrieves a list of all books")
    public ResponseEntity<List<Book>> getAllBooks() {
        // Implementation to retrieve all books
    }

    @GetMapping("/{id}")
    @Operation(summary = "Get book by ID", description = "Retrieves a book based on ID")
    public ResponseEntity<Book> getBookById(@PathVariable Long id) {
        // Implementation to retrieve a book by ID
    }

    @PostMapping
    @Operation(summary = "Create a new book", description = "Creates a new book")
    public ResponseEntity<Book> createBook(@RequestBody Book book) {
        // Implementation to create a new book
    }

    @PutMapping("/{id}")
    @Operation(summary = "Update an existing book", description = "Updates an existing book based on ID")
    public ResponseEntity<Book> updateBook(@PathVariable Long id, @RequestBody Book book) {
        // Implementation to update an existing book
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "Delete book by ID", description = "Deletes a book based on ID")
    public ResponseEntity<Void> deleteBook(@PathVariable Long id) {
        // Implementation to delete a book by ID
    }
}

在這個控制器中，我們使用了 Spring 的註解來定義不同的 API 端點，並使用 SpringDoc OpenAPI 的註解（如 @Operation 和 @Tag）來提供有關每個端點的描述。這些註解將被 SpringDoc OpenAPI 掃描，並用於生成 API 文件。

4.2 查看生成的 API 文件

一旦你的應用程式運行，你可以訪問以下 URL 來查看生成的 API 文件和 Swagger UI：

Swagger UI：http://localhost:8080/swagger-ui.html（同樣，根據你的應用程式端口和路徑進行調整）

你將能夠在 Swagger UI 中看到自動生成的 API 文件，並使用交互式界面來測試每個 API 端點。

這樣，你已經成功地使用 SpringDoc OpenAPI 記錄你的 Spring Boot REST API，並且可以通過 Swagger UI 方便地查看和測試 API。

5. 整合 Spring Security：以 Bearer Token 身份驗證為例

Spring Security 是 Spring 生態系統中用於處理身份驗證和授權的框架。在記錄 API 時，集成 Spring Security 可以幫助開發者確保 API 的安全性和可用性。

5.1 設定 Spring Security

首先，確保已將 Spring Security 添加到你的 Spring Boot 專案依賴中。你可以在pom.xml文件中添加以下依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

然後，你需要配置 Spring Security，以確保只有授權的使用者(開發人員)可以訪問 API。以下是一個簡單的配置示例：

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(authorize -> authorize
                        // 下面這行表示白名單，也就是說可以不用經過身分驗證就可以訪問的路徑
                        .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/api/test/**").permitAll()
                        // 下面這行表示除了白名單以外的路徑都需要經過身分驗證才可以訪問!!
                        .anyRequest().authenticated()
                )
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
        return http.build();
    }
}

5.2 設置SpringDoc OpenAPI的安全機制

@OpenAPIDefinition
@Configuration
public class SpringDocConfig {

  @Bean
  public OpenAPI baseOpenAPI() {
    final String securitySchemeName = "bearerAuth";

    return new OpenAPI()
        .info(new Info()
              .title("Ironman2023 API Documentation - 2023 IT鐵人賽範例")
              .description("SpringBoot 3.x application")
              .version("v0.0.1")
              .license(new License().name("Your License").url("http://springdoc.org"))
              .contact(new Contact().name("Ian Liu").email("ianliu@example.com").url("Your Website URl"))
        )
        .components(new Components()
              .addSecuritySchemes( securitySchemeName, new SecurityScheme()
                    .name(securitySchemeName)
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")
              )
        );
    }
}

上述配置指示 SpringDoc OpenAPI 記錄了 Bearer Token 身份驗證，並使用 "bearerAuth" 作為安全機制的名稱，並指定了 Token 的格式（這裡是 JWT）。

這樣，當你訪問 API 文件時，將包括相關的安全機制信息，以幫助使用者(開發人員)理解如何進行身份驗證。

5.3 查看生成的 API 文件

一旦你的應用程式運行，你可以訪問以下 URL 來查看生成的 API 文件和 Swagger UI：

Swagger UI：http://localhost:8080/swagger-ui.html（同樣，根據你的應用程式端口和路徑進行調整）
- 需要通過身分驗證的API旁邊都多了一個鎖頭圖式
- 如果不想每次在測試API的時候都要輸入身分驗證的授權碼，可以點擊下圖標示的按鈕，可在那設置全局的授權碼。
測試是否真的無法訪問，如下圖所示。

6. 總結

本文深入介紹了 SpringDoc OpenAPI，展示了如何使用它來自動生成符合 OpenAPI 3.0 規範的 API 文件。我們學習了如何配置 SpringDoc OpenAPI，記錄 Spring Boot REST API，以及如何整合 Spring Security 以確保 API 的安全性。這個技術不僅可以節省開發時間，還可以提高 API 文件的一致性和可讀性。

總結一下我們在本文中學到的主要知識點：