打造引人入胜的API开发者文档体验

互联网的发展促使越来越多的组织开发其 API 来传输数据并运行他人开发的功能。在详细描述 API 时，传统方法往往力不从心。这背后有许多原因，但最重要的一点是文档与代码是分开维护的。

由于 API 没有前端界面，文档就是它的用户界面。开发者依赖格式清晰、内容最新的文档来理解 API 的工作原理以及如何将其集成到自己的代码中。简而言之，没有文档，开发者就无法使用 API。

我们如何创造令人愉悦的开发者体验呢？Baklib 现已扩展其对 API 文档的支持。在本博客中，我们将深入探讨如何高效使用此功能。

API 文档功能允许您描述和记录您的 API。该功能支持上传多个 API 定义文件，这些文件可用于生成交互式文档、客户端库及其他相关产物。除了可以上传 JSON 或 YAML 格式的 API 定义文件外，您还可以使用托管 URL 将 API 定义导入到 Baklib 的 API 文档模块中。

它是如何工作的？

为 API 创建一个规范，定义 API 应如何运行以及应实现什么功能。这包括定义 API 公开的端点（URL）、API 使用的请求和响应格式、API 支持的 HTTP 方法（例如 GET、POST、PUT、DELETE），以及使用 API 必须满足的任何身份验证或授权要求。

设计API可以使用多种工具和方法，包括Swagger和Postman等可视化建模工具，以及OpenAPI和RAML等设计优先方法。这些工具允许您以机器可读的格式（如JSON或YAML）定义和记录API，然后可以用于生成文档、测试用例和实现API的代码。

一旦您对API定义满意，导航到开发文档，然后选择“新建API”或通过单击“新建API参考”按钮添加您的OpenAPI（OAS/Swagger）文件开始。页面将打开选项，您可以根据要使用的格式选择源，如果您有托管URL，请选择该选项并输入托管的API URL。我们建议在API通信中使用HTTPS（超文本传输安全协议）而不是HTTP（超文本传输协议），因为HTTPS提供加密连接，有助于保护客户端和服务器之间传输的数据。

OpenAPI 2.0是该规范的第一个版本，目前仍被广泛使用。OpenAPI 3.0是该规范的最新版本，它引入了多项新功能和改进。您可以使用任一版本来定义您的API。

通过提供可点击的“选择文件”按钮或拖放功能使用交互式界面，上传文件更加方便，无需手动输入文件路径或使用命令行上传文件。

在上传或更新API定义时，遇到错误和警告是常见情况，尤其是当定义文件庞大或复杂时。这些错误和警告可能由多种原因引起，例如API定义文件中的语法错误、定义中信息缺失或不正确，或者与其他API定义或资源存在冲突。

在管理API更新时，将错误和警告分开显示会很有帮助，您可以更容易地识别和优先处理需要解决的问题，并能够及时采取措施进行修复。

为了帮助管理和跟踪这些错误和警告，Baklib为每个API定义提供了“查看日志”选项，用于维护API更新的日志记录。要访问此功能，请导航至API参考部分，选择任意API菜单，即可找到“查看日志”选项。该选项记录了每次API更新的日期、时间和详细信息，以及发生的任何错误或警告。这使您能够识别API定义中的问题并进行故障排除，并随时间跟踪API的更改和更新。与手动维护不同，您还可以生成CSV格式的API更新日志，其中包含更具体的详细信息，如操作类型、导入者、日期时间、错误和警告消息以及路径，以便识别和解决可能出现的任何问题。

在为特定任务选择文件类型时，考虑不同文件类型的能力非常重要。文件上传选项中提到了文件类型，而URL则提供了重新同步和API定义选项。如果在更新API定义文件时API模式发生了变化，然后重新生成了API客户端或服务器代码，您可以重新同步模式以立即反映这些更改。同样，如果您有一个使用API的API客户端，并希望确保它与最新的模式更改保持同步，您可以更新API定义文件。这将确保服务器代码与更新后的API模式保持一致。

URL提供的查看API定义选项，可用于了解API是如何实现的以及定义是如何存储的。如果您的API经常变更，或者同时在使用多个版本的API，这个功能会特别有用。

准备好将您的开发文档提升到新的水平了吗？立即预约 Baklib 的演示！

上传API定义后，它会以交互方式对端点进行分类并创建文档文章，这对于希望使用您API的开发人员来说是一个有用的资源。从API定义生成的文档通常包括可用端点列表、每个端点的参数和请求/响应格式描述以及如何使用端点的示例。还允许您包含其他信息，例如代码示例和API工作原理的说明。通常，现在API定义被视为Baklib文章，端点文章可以轻松重命名、隐藏、删除，并在需要时移动到其他API定义。支持多种端点类型，包括GET、POST、PUT、DELETE等。您可以查看可用端点、每个端点所需的参数以及每个端点返回的响应。

除了指定API的端点外，开发文档还支持一系列其他功能，例如身份验证、授权和错误处理。它可以用于为Web、移动和其他类型的应用程序设计API。

一旦类别在门户中发布，就可以导航到知识库站点执行操作。显示了带有端点的相同类别树状视图。您可以使用编辑器服务器中的下拉菜单选择要测试的HTTP方法（例如，GET、POST、PUT、DELETE）和端点。要使用基本身份验证向API端点发出GET请求，您需要分别提供客户端ID和密钥作为用户名和密码。

这通常可以通过在您正在使用的API客户端或集成中选择“基本认证”类型来完成。请注意，所需的参数已在“试用”面板中传递。认证细节被缓存起来，以便通过将其包含在请求头中，供未来的API请求使用，这有助于实现无缝且省时的工作流程。使用凭据请求API令牌。这通常涉及向认证端点发出POST请求，并在请求体中传递您的凭据。然后，API提供商将验证您的凭据，如果有效，将在响应中返回API令牌。 在提供的表单字段中输入任何必需的参数。点击“试用”按钮。这将向API端点发送请求，并在右侧面板中显示HTTP状态码的响应和响应负载（如果有）。您可以使用此信息来判断API是否按预期运行。以不同格式（如JSON、XML或HTML）查看响应。响应的内容类型在HTTP响应中通过“Content-Type”头部指定。例如，如果响应包含JSON格式的数据，“Content-Type”头部可能设置为“application/JSON”。 响应的内容类型可能很重要，原因有几个。例如，客户端可以使用它来解析和解释响应中的数据。客户端还可以使用它来确定如何处理响应，例如在Web浏览器中渲染或在移动应用程序中显示。

在某些情况下，一个API可能为单个端点支持多种内容类型。例如，一个端点可能同时支持JSON和XML格式，客户端可以通过在请求中设置“Accept”标头来指定他们偏好的格式。然后，API可以在响应中使用“Content-Type”标头来指示返回数据的格式。重复步骤3-6以测试其他端点，或使用不同的参数值测试同一端点。总的来说，使用开发文档来调用API是一个简单的过程，允许您测试API的功能并理解其工作原理。

响应示例：

在开发文档中，您可以为API中的每个端点指定响应示例。这有助于为测试目的记录API。

以下是一个在Swagger中为返回JSON格式用户列表的端点指定响应示例的方法：

/users:

get:

summary: 检索用户列表
responses:
  200:
    description: 成功
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/User'
        examples:
          user-list:
            value:
              - id: 1
                name: John Smith
                email: john.smith@example.com
              - id: 2
                name: Jane Doe
                email: jane.doe@example.com

在此示例中，端点名为“/users”，它支持GET请求。响应包含一个表示成功的200状态码，数据以JSON格式返回。“examples”字段包含了可能返回的响应数据的示例。

您还可以为单个端点指定多个示例，每个示例都包含不同的数据集。这有助于演示端点在不同条件下或使用不同输入数据时的行为。

💛🧡🧡客户评价：Next.js 的 Baklib 模板和指南有点难以理解，因为似乎有不少具有不同功能集的模板和指南。希望设置过程总体上能够更加简化和清晰。我想我已经浏览了 4 个官方模板，它们在设置获取函数等方面都有完全不同的逻辑。不过，部分原因可能与 Next.js 本身最近的重大变化有关。手动输入模式可能很乏味，尤其是当涉及到条件验证等更复杂的逻辑时。像竞争对手的产品（例如 Baklib ）这样的可视化界面会很棒。设置实时编辑和草稿预览似乎过于复杂。根据我的经验，演示模式总体上被证明是相当不稳定的。

我之前提供的示例旨在展示如何在Swagger中为返回JSON格式用户列表的端点指定响应示例。它并非完整的API定义，也不应直接用于生成代码或其他产物。

要从API定义生成代码或其他产物，通常需要提供更完整、更准确的API表示，包括有关端点、参数、请求和响应格式以及API其他方面的详细信息。

代码示例

代码示例允许开发人员使用多种编程语言为API生成客户端库。支持Shell脚本、Python、Java、JavaScript和C#，使开发人员更容易使用API。利用生成的代码，可以将客户端库导入您的应用程序，并用它向API发出请求。

总的来说，获取和使用开发文档是与API交互的有效方式，可以帮助您自动化此过程并为API生成代码片段。

查看我们的视频，了解如何编写真正帮助用户的开发人员文档，并提供保持清晰、简洁和以受众为中心的技巧！

最后的话

随着越来越多的公司认识到开发文档的重要性，并为此过程投入适当的时间和资源，开发文档正变得越来越好。下次您需要创建高质量的开发文档时，不妨试试Baklib的开发文档功能，它会让您的工作更轻松。我们以简化开发文档的难度为荣，并期待协助您完成相关工作。