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 开发人员使用。