使用README风格的API文档提升您的API设计

API文档的一个常见问题是，它们往往只关注单个操作的记录，而忽略了多个操作之间的关联以及现实世界中复杂的工作流。这种孤立的设计虽然在单个API操作上可能显得合理，但真正的挑战在于用户如何将这些操作协调起来以实现特定目标。如果文档未能清晰地指导用户完成这些流程，可能会导致开发人员的困惑和挫折，进而影响API的采用和整体效果。

OpenAPI规范：构建坚实的技术基础

在深入探讨README风格的文档之前，首先需要通过OpenAPI规范是一种行业标准格式，能够为API提供机器可读的描述，包括端点、参数、请求/响应结构以及错误代码等内容。

以下是一个假设的电子商务API的OpenAPI规范片段示例：

paths:
  /products/{productId}:
    get:
      summary: 获取产品信息
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回产品信息

通过OpenAPI规范，我们可以全面了解API的设计。然而，仅仅依赖这种技术参考文档，可能会给API用户带来一些问题。

传统API文档的问题

传统的API文档通常采用技术参考的方式，详细说明每个端点的参数、请求/响应格式和错误代码。这种方法虽然提供了必要的信息，但却忽略了用户实际使用API时的整体交互流程。这种不足可能导致以下问题：

用户难以理解如何将多个API操作组合起来完成任务。
缺乏实际场景的指导，增加了用户的学习成本。
无法有效支持复杂的业务流程。

因此，仅依靠传统的API文档，无法满足用户在实际使用中的需求。

README风格的API文档：以用户为中心的方法

README风格的API文档将关注点从单个操作转移到用户的实际工作流。它通过现实场景展示API的使用方式，演示如何将多个操作串联起来以实现特定目标。

README风格文档的核心内容

README风格的文档通常包括以下内容：

用户场景：描述用户可能遇到的实际问题。
操作流程：详细说明如何通过API完成任务。
代码示例：提供清晰的代码片段，帮助用户快速上手。
错误处理：指导用户如何应对可能出现的问题。

这种方法的优势

提升用户体验：通过清晰的工作流指导，减少用户的困惑。
降低学习成本：帮助用户快速理解API的实际用途。
促进API采用：更直观的文档能够吸引更多开发者使用API。

实施README风格的API文档

以下是创建README风格API文档的几个实用步骤：

确定常见用户工作流

分析用户需求，识别他们希望通过API完成的常见任务。
制定清晰的工作流程

使用简洁的语言描述每个工作流，明确操作的顺序和逻辑。
提供代码片段和示例

针对不同编程语言，提供实际可运行的代码片段，帮助用户快速实现目标。
与现有工具集成

利用现有的文档平台和工具，将README风格的文档与API参考资料无缝结合。

对于复杂的API，可以从最常见的工作流入手，逐步扩展到其他场景。

示例：README风格的用户工作流

以下是一个电子商务API的README风格工作流示例，展示如何通过API查看产品详情、创建订单并添加商品：

使用/products/get操作检索所需产品的信息。
使用/orders/create操作创建新订单。
使用/orders/{orderId}/items操作将检索到的产品添加到订单中。

以下是一个代码片段示例：

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规范中提供了便利。开发者可以使用Markdown格式将工作流细节直接包含在OpenAPI文档中，并通过Bump.sh平台进行渲染。

以下是一个示例：

x-topics:
  - title: 创建新订单
    content: |
      使用/orders/create操作创建新订单。
  - title: 添加商品到订单
    content: |
      使用/orders/{orderId}/items操作将商品添加到订单中。

如果不希望将工作流嵌入OpenAPI规范中，也可以通过外部JSON引用将文档与API规范分离。

OpenAPI工作流规范：API工作流的未来

OpenAPI倡议正在开发一种新的工作流规范，旨在正式定义和记录API工作流。这种规范将提供结构化的方法，捕获实现特定任务所需的操作序列，从而进一步优化用户体验。

以下是一个潜在的工作流规范示例：

workflows:
  createOrderAndAddItems:
    description: 创建新订单并向其中添加商品
    steps:
      - operationId: getProductById
        path: /products/{productId}
      - operationId: createOrder
        path: /orders
      - operationId: addItemsToOrder
        path: /orders/{orderId}/items

这种规范化的方式将帮助开发者更高效地设计和记录复杂的API工作流。

结论

README风格的API文档通过关注用户实际工作流，显著提升了API的可用性和用户体验。它不仅弥合了技术规范与实际使用之间的差距，还为开发者提供了收集用户反馈的机会，从而不断优化API设计。

采用这种文档风格的好处包括：

提高用户对API的理解和使用效率。
减少开发者和用户之间的沟通障碍。
提升API的采用率和成功率。

通过结合Bump.sh的x-topic扩展和即将推出的OpenAPI工作流规范，开发者可以创建更直观、标准化且用户友好的API文档，从而推动API的广泛应用和成功。

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