5.2. 在 Developer Portal 中发布 ActiveDoc

在本教程结束时,您将在开发人员门户中发布您的 ActiveDocs,您的 API 文档也将是自动化的。

先决条件

  • 开发人员门户上需要使用符合 REST API 的 OpenAPI 规范(OAS)规范。

步骤

  • 将以下代码片段添加到 Developer Portal 的任何页面的内容。您必须通过 3scale 管理门户进行此操作。

    注意

    SERVICE_NAME 应为服务规格的系统名称,示例中为 pet_store

    <h1>Documentation</h1>
    <p>Use our live documentation to learn about Echo API</p>
    {% active_docs version: "2.0" services: "SERVICE_NAME" %}
    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %} {% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %} {% include 'shared/swagger_ui' %}
    <script type="text/javascript">
      $(function () {
        {% comment %}
          // you have access to swaggerUi.options object to customize its behaviour
          // such as setting a different docExpansion mode
          window.swaggerUi.options['docExpansion'] = 'none';
          // or even getting the swagger specification loaded from a different url
          window.swaggerUi.options['url'] = "http://petstore.swagger.io/v2/swagger.json";
        {% endcomment %}
        window.swaggerUi.load();
      });
    </script>

在 Developer Portal 中发布 ActiveDocs 时会考虑以下几个额外注意事项:

  • 您只能在一个页面中指定一项服务。如果要显示多个规格,最佳的做法是在不同的页面上执行该操作。
  • 此片段需要 jQuery,它默认包含在 Developer Portal 的主布局中。如果从主布局中删除 jQuery 依赖项,您必须在包含 ActiveDocs 的页面上添加此依赖项。
  • 确保管理门户中启用了 Liquid 标签。
  • Liquid tag {{ '{% active_docs 版本中使用的版本:"2.0" ' }}%} 应该与 Swagger spec 对应。

如果要从外部源获取规格,请按如下所示更改 JavaScript 代码:

$(function () {
 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
 window.swaggerUi.load();
});

请注意,包含规范来源 的行 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL"; 位于注释块之外。

验证步骤

在创建了 OpenAPI 规范将其添加到 3scale 后,到了发布规范并将其链接到开发人员门户上,供 API 开发人员使用。