編寫OpenAPI規范文檔是一個系統化的過程，它涉及定義API的各個方面，包括路徑、參數、請求和響應體、安全定義等。以下是編寫OpenAPI規范文檔的基本步驟：

<i id='68mo6'></i>

1. 了解OpenAPI規范版本

首先，確定你將使用哪個版本的OpenAPI規范。目前，OpenAPI規范的兩個主流版本是OpenAPI 2.0（也稱為Swagger 2.0）和OpenAPI 3.0。兩者在語法和功能上有所不同，OpenAPI 3.0提供了更多的功能和改進。

2. 定義API的基本屬性

在文檔的根級別，定義API的基本信息，如：

• openapi：規范的版本號。
• info：API的元數據，包括標題、描述、版本等。
• servers：API的服務器URL列表。

例如：

openapi: 3.0.0
info:
  title: 示例API
  description: 這是一個示例API的OpenAPI文檔。
  version: 1.0.0
servers:
  - url: XXXX

3. 定義路徑和操作

對于API中的每個端點，定義一個路徑對象，包括：

• path：API的URL路徑。
• operation：HTTP操作（如GET、POST、PUT、DELETE）及其詳細信息。

例如：

paths:
  /users:
    get:
      summary: 獲取用戶列表
      operationId: listUsers
      responses:
        '200':
          description: 用戶列表返回成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

4. 定義請求和響應結構

使用components部分定義請求和響應的模型結構，包括：

• schemas：定義數據結構，如請求體和響應體。
• parameters：定義可復用的參數。
• requestBodies：定義請求體。
• responses：定義響應體。

例如：

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email

5. 定義安全方案

如果API需要認證，定義安全方案和API密鑰：

security:
  - api_key: []
securityDefinitions:
  api_key:
    type: apiKey
    name: X-API-Key
    in: header

6. 使用工具生成和驗證文檔

可以使用Swagger UI、Redoc等工具來生成交互式文檔，并使用Swagger Codegen等工具自動生成客戶端代碼。同時，這些工具也可以幫助驗證OpenAPI文檔的正確性。

7. 測試和迭代

在實際API開發過程中，不斷測試和更新OpenAPI文檔，確保文檔與API的實際行為保持一致。

編寫OpenAPI規范文檔是一個迭代的過程，需要與API的設計和開發緊密結合。隨著API的演進，文檔也需要相應地更新。