5.2. 在开发者门户中发布 ActiveDocs
在本教程结束时,您将在开发人员门户中发布您的 ActiveDoc,您的 API 文档将自动执行。
先决条件
- 需要您的 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>
在开发者门户中发布 ActiveDocs 时,这些额外注意事项:
- 在一个页面中只能指定一个服务。如果要显示多个规格,最佳的方法是在不同的页面上执行它。
- 这个片段需要 jQuery,它默认包含在开发人员门户的主布局中。如果从主布局中删除 jQuery 依赖项,您必须将这个依赖项添加到包含 ActiveDocs 的页面中。
- 确保管理门户上启用了 Liquid 标签。
-
OAS 2.0
{{ '{% active_docs version: "2.0" ' }}%}
的 Liquid 标签中使用的版本应该与 Swagger spec 的对应版本。
如果要从外部来源获取您的规格,请按如下所示更改 JavaScript 代码:
$(function () { window.swaggerUi.options['url'] = "SWAGGER_JSON_URL"; window.swaggerUi.load(); });
请注意,包含规范来源的行 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
在注释块之外。
验证步骤
在创建 OpenAPI 规格 并将其添加到 3scale 后,需要发布规格并将其链接到您的 API 开发人员使用。