5.2. 在开发者门户中发布 ActiveDocs

先决条件

• 需要您的 REST API 兼容的 OpenAPI 规格(OAS)在开发者门户上打开 ActiveDocs。

流程

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

  注意

  SERVICE_NAME 应当是服务规格的系统名称，本例中为 pet_store。

  使用 OAS 3.0 的开发者门户配置

  {% content_for javascripts %}
   {{ 'active_docs.js' | javascript_include_tag }}
  {% endcontent_for %}
  
  {% assign spec = provider.api_specs.first %}
  
  <h1>Documentation</h1>
  
  <div class="swagger-section">
   <div id="message-bar" class="swagger-ui-wrap"></div>
   <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
  </div>
  
  <script type="text/javascript">
   (function () {
     var url = "{{spec.url}}";
     var serviceEndpoint = "{{spec.api_product_production_public_base_url}}"
     SwaggerUI({ url: url, dom_id: "#swagger-ui-container" }, serviceEndpoint);
   }());
  </script>

  使用 OAS 2.0 的开发者门户配置

  <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 behavior
        // 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>

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