第 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。