第 3 章 将 ActiveDocs 添加到 3scale

3scale 提供了一个框架来为您的 API 创建交互式文档。

借助 OpenAPI 规范(OAS),您拥有 API 的功能文档,可帮助您的开发人员探索、测试和集成您的 API。

3.1. 在 3scale 中设置 ActiveDocs

您可以在 3scale 用户界面中将 ActiveDocs 添加到 API 中,以获取为您的 API 创建交互式文档的框架。

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2.11 实例租户的凭据(令牌provider_key)。

步骤

  1. 导航到管理门户中的 [your_API_name] → ActiveDocs。3scale 显示您的 API 服务规格列表。这最初为空。

    您可以根据需要添加更多服务规格。通常,每个服务规格都对应于您的一个 API。例如,3scale 具有每个 3scale API 的规格,如服务管理、帐户管理、分析分析和计费。

  2. 点击 Create a new spec

    添加新服务规格时,请执行以下操作:

    • Name
    • 系统名称.这需要引用 Developer Portal 中的服务规格。
    • 选择是否希望发布该规范。如果没有发布,则 Developer Portal 中将不提供新的规范。

      注意

      如果您创建但不发布新规范,则会在稍后进行选择时供您发布。

    • 添加仅供您使用的描述。
    • 添加 API JSON 规格。

      根据 OpenAPI 规范(OAS) 提出的规范生成 API 规格。在本教程中,我们假设您已具有与 API 的有效 OAS 兼容规格。

使用第一个 ActiveDoc

添加第一个 ActiveDoc 后,您可以在 [your_API_name] → ActiveDocs 中 看到它。您可以根据需要编辑、删除或将其从公共切换到私有。您可以从 API 分离,或将其附加到任何其他 API。您可以查看所有 ActiveDocs,无论它们是否附加到 Audience → Developer Portal → ActiveDocs 中的 API。

您可以通过单击您给定的服务规格的名称来预览 ActiveDocs 的样子,例如 Pet Store。即使规范尚未发布,您也可以执行此操作。

这是 ActiveDoc 类似的内容:

ActiveDocs 新规格视图