第 2 章 如何配置 OpenAPI 规格


要使 OpenAPI 规格与 3scale 一同使用,需要根据您要使用的版本进行正确配置。

先决条件

  • 定义 API 的 OpenAPI 文档。
  • 3scale 2.14 实例租户的凭据(tokenprovider_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">&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>

要更新模板,请将默认的 Documentation 页面替换为 Configure the Developer Portal 中包含的代码片段,使用 OAS 3.0

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.