第 2 章 如何配置 OpenAPI 规格

要使 OpenAPI 规范与 3scale 协同工作,需要为要使用的版本正确配置。

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2.11 实例租户的凭据(令牌provider_key)。

2.1. OpenAPI 规范 3.0 使用 3scale

3scale 提供对使用 OAS 3.0 的以下支持:

  • Developer Portal 中更新了 swagger-ui 以支持 OAS 3.0
  • swagger-ui 现在作为 webpack 资产(node_modules)包含在内。以前,它是从 Content Delivery Network(CDN)中添加的。
  • 在管理门户中,任何新的 OAS 3.0 文档都会通过使用 swagger-ui 提供的功能来自动识别和处理。请注意,此功能需要在 Developer Portal 中进行配置。

您可以添加 OAS 3.0 规格到 ActiveDocs 中,并在 Developer Portal 中显示它们,考虑以下几点:

  • 您必须手动升级模板。
  • 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 更新 Developer Portal

如果您已在 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">&nbsp;</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>

要更新模板,将默认文档页面替换为 第 2.1.1 节 “使用 OAS 3.0 配置开发人员门户” 中包含的代码片段。