知識庫 / Spring / Spring Boot RSS 訂閱

paths:
  /account:
    get:
      tags:
        - accounts
      summary: Get account information
      description: Get account information using account number
      operationId: getAccount
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNotFoundError'
  /account/deposit:
    post:
      tags:
        - accounts
      summary: Deposit amount to account
      description: Initiates a deposit operation of a desired amount to the account specified 
      operationId: depositToAccount
      requestBody:
        description: Account number and desired amount to deposit
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
        required: true
      responses:
        204:
          description: Success
        404:
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNotFoundError'

注意：再次提醒，YAML 解釋器會顯示一些錯誤，我們將在第 4.3 節中解決它們。目前可以忽略這些錯誤。

文檔中包含了很多內容。為了便於理解，我們將其分解為各個部分，逐個分析關鍵詞：

• paths – 定義 API 資源 /account 和/account/deposit。 在資源下，必須定義可用的 get 和 post 動詞。
• tags – 它所屬的組。應與第 4.1 節中描述的相同標籤名稱。
• summary – 端點所做事情的簡要信息。
• description – 關於端點工作方式的詳細信息。
• operationId – 描述操作的唯一標識符。
• requestBody – 包含 description、content 和 required 關鍵詞的請求負載。我們將在第 4.3 節中定義內容 schema。
• responses – 所有可用響應代碼的列表。每個響應代碼對象包含 description 和 content 關鍵詞。我們將定義該內容 schema 在第 4.3 節中。
• content: 消息的 HTTP Content-Type。

4.3. 定義數據模型組件

最後，讓我們為我們的 API 創建數據模型對象：請求和響應主體以及錯誤消息。要實現這一點，請在 YAML 編輯器的根級別添加以下結構：

components:
  schemas:
    Account:
      type: object
      properties:
        balance:
          type: number
    AccountNotFoundError:
      type: object
      properties:
        message:
          type: string
    DepositRequest:
      type: object
      properties:
        accountNumber:
          type: string
        depositAmount:
          type: number

在添加了上述內容後，編輯器的所有解釋錯誤都應該消失。

在上述 YAML 代碼中，我們定義了與第 4.2 節的 schema 關鍵詞中相同的組件。我們可以像使用組件一樣，隨意地重複使用它們。例如，AccountNotFoundError 對象被用於兩個端點的 404 響應代碼中。讓我們分別檢查代碼中的關鍵詞：

• components – 組件的根級別關鍵詞。
• schemas – 所有對象定義的列表。
• type – 字段的類型。如果使用 object 類型，我們還需要定義 properties 關鍵詞。
• properties – 所有對象字段名稱及其類型的列表。

4.4. 審核 API 文檔

此時，API已上線供產品相關方進行審核。我們知道 API-First 開發的主要優勢在於能夠快速失敗或成功，而無需在開發階段浪費時間。因此，請確保每個人都審核並與擬議的 API 資源、響應代碼、數據模型以及 API 的描述和職責進行協作，然後再進入開發階段。

在團隊達成設計方案後，他們可以並行地開發 API。

5. 將 YAML 文檔導入 Spring Boot 應用

本節介紹了開發者如何將 YAML 文檔導入應用程序並自動生成 API 骨架代碼。

首先，我們需要在 /src/main/resources 目錄下創建一個名為 account_api_description.yaml 的空 YAML 文件。然後，我們將 account_api_description.yaml 文件中的內容替換為 Swagger 在線編輯器中的完整 YAML 代碼。最後，我們需要將 openapi-generator-maven-plugin 插件添加到 Spring Boot Application 的 <plugins> 標籤中，位於 pom.xml 文件中：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.2.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <skipValidateSpec>true</skipValidateSpec>
                <inputSpec>./src/main/resources/account_api_description.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <configOptions>
                    <openApiNullable>false</openApiNullable>
                    <interfaceOnly>true</interfaceOnly>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

您可以在 OpenAPI 插件教程中找到此處使用的代碼。

現在，讓我們通過運行以下命令從 YAML 文件生成服務器端代碼：

mvn clean install

之後，我們可以檢查生成的代碼在 target 文件夾中：

從那裏，開發人員可以使用生成的類作為開發階段的起點。例如，我們可以使用下面的 AccountApi 接口，並使用 AccountController 類：

@Controller
public class AccountController implements AccountApi {
    @Override
    public ResponseEntity<Void> depositToAccount(DepositRequest depositRequest) {
        //Execute the business logic through Service/Utils/Repository classes
        return AccountApi.super.depositToAccount(depositRequest);
    }

    @Override
    public ResponseEntity<Account> getAccount() {
        //Execute the business logic through Service/Utils/Repository classes
        return AccountApi.super.getAccount();
    }
}

被覆蓋的方法 depositToAccount 和 getAccount 分別對應於 POST /account/deposit 和 GET /account 端點。

6. 結論

在本文中，我們學習瞭如何使用 API-First 開發方法，結合 Spring-Boot 和 OAS。我們還探討了 API-First 的優勢以及它如何幫助現代敏捷軟件開發團隊。使用 API-First 的最重要原因在於它提高了敏捷性和在創建 API 時減少了浪費的時間。通過這種方法，我們可以更快地進行設計草案、迭代更改和提供反饋。

另一個使用 API-First 方法的好理由是利益相關者無需等待開發人員完成代碼即可開始工作。QA 工程師、作家、經理和開發人員在初始 API 設計文檔創建後，可以並行工作。