第 2 章 如何配置 OpenAPI 规格
要使 OpenAPI 规格与 3scale 一同使用,需要根据您要使用的版本进行正确配置。
先决条件
- 定义 API 的 OpenAPI 文档。
-
3scale 2.14 实例租户的凭据(
token
或provider_key
)。
2.1. 3scale API 管理的 OpenAPI 规格 3.0 使用
3scale 提供以下对使用 OAS 3.0 的支持:
-
在开发者门户中更新了
swagger-ui
,以支持 OAS 3.0 -
swagger-ui
现在包含一个 webpack asset(node_modules
)。以前,它从 Content Delivery Networks(CDN)添加。 -
在管理门户中,任何新的 OAS 3.0 文档都会使用
swagger-ui
提供的功能自动处理并进行相应处理。请注意,这个功能需要在 Developer Portal 中进行配置。
您可以将 OAS 3.0 规格添加到 ActiveDocs 中,并在开发者门户中显示它们,请考虑以下点:
- 您必须手动升级模板。
- ActiveDoc 在尝试请求时没有额外的功能,如凭证注入,使用诸如服务名称等实际数据的自动完成功能。
2.1.1. 使用 OAS 3.0 配置开发人员门户
此片段包括新版本的 swagger-ui
,并呈现第一个可用的 ActiveDoc。请注意,它还呈现 OAS 2.0,但没有任何常见的 ActiveDocs 功能。
对 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 3.0 更新开发人员门户。
如果您在 3scale 2.8 中配置了 OAS 3.0,并希望继续使用 OAS 3.0,则需要更新该模板。
这是要配置的模板:
{% content_for javascripts %} {{ 'active_docs.js' | javascript_include_tag }} {% endcontent_for %} <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 = "{{provider.api_specs.first.url}}"; SwaggerUI({ url: url, dom_id: "#swagger-ui-container" }); }()); </script>
要更新模板,请将默认的 Documentation 页面替换为 Configure the Developer Portal 中包含的代码片段,使用 OAS 3.0。