OpenAPI規(guī)范：構(gòu)建堅實的技術(shù)基礎

在深入探討README風格的文檔之前，首先需要通過OpenAPI規(guī)范是一種行業(yè)標準格式，能夠為API提供機器可讀的描述，包括端點、參數(shù)、請求/響應結(jié)構(gòu)以及錯誤代碼等內(nèi)容。

以下是一個假設的電子商務API的OpenAPI規(guī)范片段示例：

paths:
  /products/{productId}:
    get:
      summary: 獲取產(chǎn)品信息
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回產(chǎn)品信息

通過OpenAPI規(guī)范，我們可以全面了解API的設計。然而，僅僅依賴這種技術(shù)參考文檔，可能會給API用戶帶來一些問題。

傳統(tǒng)API文檔的問題

傳統(tǒng)的API文檔通常采用技術(shù)參考的方式，詳細說明每個端點的參數(shù)、請求/響應格式和錯誤代碼。這種方法雖然提供了必要的信息，但卻忽略了用戶實際使用API時的整體交互流程。這種不足可能導致以下問題：

• 用戶難以理解如何將多個API操作組合起來完成任務。
• 缺乏實際場景的指導，增加了用戶的學習成本。
• 無法有效支持復雜的業(yè)務流程。

因此，僅依靠傳統(tǒng)的API文檔，無法滿足用戶在實際使用中的需求。

README風格的API文檔：以用戶為中心的方法

README風格的API文檔將關(guān)注點從單個操作轉(zhuǎn)移到用戶的實際工作流。它通過現(xiàn)實場景展示API的使用方式，演示如何將多個操作串聯(lián)起來以實現(xiàn)特定目標。

README風格文檔的核心內(nèi)容

README風格的文檔通常包括以下內(nèi)容：

• 用戶場景：描述用戶可能遇到的實際問題。
• 操作流程：詳細說明如何通過API完成任務。
• 代碼示例：提供清晰的代碼片段，幫助用戶快速上手。
• 錯誤處理：指導用戶如何應對可能出現(xiàn)的問題。

這種方法的優(yōu)勢

• 提升用戶體驗：通過清晰的工作流指導，減少用戶的困惑。
• 降低學習成本：幫助用戶快速理解API的實際用途。
• 促進API采用：更直觀的文檔能夠吸引更多開發(fā)者使用API。

實施README風格的API文檔

以下是創(chuàng)建README風格API文檔的幾個實用步驟：

1. 確定常見用戶工作流

   分析用戶需求，識別他們希望通過API完成的常見任務。

2. 制定清晰的工作流程

   使用簡潔的語言描述每個工作流，明確操作的順序和邏輯。

3. 提供代碼片段和示例

   針對不同編程語言，提供實際可運行的代碼片段，幫助用戶快速實現(xiàn)目標。

4. 與現(xiàn)有工具集成

   利用現(xiàn)有的文檔平臺和工具，將README風格的文檔與API參考資料無縫結(jié)合。

對于復雜的API，可以從最常見的工作流入手，逐步擴展到其他場景。

示例：README風格的用戶工作流

以下是一個電子商務API的README風格工作流示例，展示如何通過API查看產(chǎn)品詳情、創(chuàng)建訂單并添加商品：

1. 使用/products/get操作檢索所需產(chǎn)品的信息。
2. 使用/orders/create操作創(chuàng)建新訂單。
3. 使用/orders/{orderId}/items操作將檢索到的產(chǎn)品添加到訂單中。

以下是一個代碼片段示例：

POST /orders/1/items
Content-Type: application/json

[
  { "product_id": 123, "quantity": 2 },
  { "product_id": 456, "quantity": 1 }
]

通過這種分步指南，用戶可以輕松理解如何完成整個流程，避免了不必要的歧義。

使用Bump.sh的x-topic擴展

Bump.sh的x-topic擴展為將README風格的文檔嵌入到OpenAPI規(guī)范中提供了便利。開發(fā)者可以使用Markdown格式將工作流細節(jié)直接包含在OpenAPI文檔中，并通過Bump.sh平臺進行渲染。

以下是一個示例：

x-topics:
  - title: 創(chuàng)建新訂單
    content: |
      使用/orders/create操作創(chuàng)建新訂單。
  - title: 添加商品到訂單
    content: |
      使用/orders/{orderId}/items操作將商品添加到訂單中。

如果不希望將工作流嵌入OpenAPI規(guī)范中，也可以通過外部JSON引用將文檔與API規(guī)范分離。

OpenAPI工作流規(guī)范：API工作流的未來

OpenAPI倡議正在開發(fā)一種新的工作流規(guī)范，旨在正式定義和記錄API工作流。這種規(guī)范將提供結(jié)構(gòu)化的方法，捕獲實現(xiàn)特定任務所需的操作序列，從而進一步優(yōu)化用戶體驗。

以下是一個潛在的工作流規(guī)范示例：

workflows:
  createOrderAndAddItems:
    description: 創(chuàng)建新訂單并向其中添加商品
    steps:
      - operationId: getProductById
        path: /products/{productId}
      - operationId: createOrder
        path: /orders
      - operationId: addItemsToOrder
        path: /orders/{orderId}/items

這種規(guī)范化的方式將幫助開發(fā)者更高效地設計和記錄復雜的API工作流。

結(jié)論

README風格的API文檔通過關(guān)注用戶實際工作流，顯著提升了API的可用性和用戶體驗。它不僅彌合了技術(shù)規(guī)范與實際使用之間的差距，還為開發(fā)者提供了收集用戶反饋的機會，從而不斷優(yōu)化API設計。

采用這種文檔風格的好處包括：

• 提高用戶對API的理解和使用效率。
• 減少開發(fā)者和用戶之間的溝通障礙。
• 提升API的采用率和成功率。

通過結(jié)合Bump.sh的x-topic擴展和即將推出的OpenAPI工作流規(guī)范，開發(fā)者可以創(chuàng)建更直觀、標準化且用戶友好的API文檔，從而推動API的廣泛應用和成功。

原文鏈接: https://bump.sh/blog/using-readme-style-api-documentation-to-enhance-your-api-design