第2章 OAS の設定

本章では、Red Hat 3scale API Management 2.9 における OpenAPI Specification (OAS) の設定手順の概要について説明します。

2.1. 3scale での OAS 3.0 の使用

本セクションでは、3scale で OpenAPI Specification 3.0 (OAS 3.0) を使用する方法について説明します。

限定的なサポートにより、3scale と OAS 3.0 の組み合わせを設定することができます。例を以下に示します。

  • デベロッパーポータルで swagger-ui が更新され、OAS 3.0 がサポートされるようになりました。
  • 今回のリリースでは、swagger-ui は webpack アセット (node_modules) として組み込まれています。以前は、コンテンツ配信ネットワーク (CDN) から追加されていました。
  • 管理ポータルでは、swagger-ui が提供する機能を使用して、新しい OAS 3.0 ドキュメントが自動的に識別され、これに応じて処理されます。この機能には、デベロッパーポータル側での設定が必要になることに注意してください。

OAS 3.0 仕様を ActiveDocs に追加し、デベロッパーポータルで表示するには、以下の点を考慮してください。

  • テンプレートは手動でアップグレードする必要があります。
  • ActiveDoc には、要求の試行時のクレデンシャルインジェクションや、サービス名などの実際のデータを使用した自動補完などの追加機能がありません。

2.1.1. OAS 3.0 を使用するデベロッパーポータルの設定

デベロッパーポータルで 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>

このスニペットには、新しいバージョンの swagger-ui が含まれ、最初に利用可能な ActiveDoc をレンダリングします。OAS 2.0 もレンダリングされますが、通常の ActiveDocs 機能はない点に注意してください。

2.1.2. 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>

テンプレートを更新するには、デフォルトのドキュメンテーションページを「OAS 3.0 を使用するデベロッパーポータルの設定」に含まれるスニペットに置き換えます。

2.2. 3scale での OAS 2.0 の使用

本セクションでは、3scale で OpenAPI Specification 2.0 (OAS 2.0) を使用する方法について説明します。

OAS 2.0 仕様を ActiveDocs に追加し、デベロッパーポータルで表示するには、以下の点を考慮してください。

  • テンプレートは手動でアップグレードする必要があります。
  • ActiveDoc には、要求の試行時のクレデンシャルインジェクションや、サービス名などの実際のデータを使用した自動補完などの追加機能がありません。

デベロッパーポータルで OAS 2.0 を設定するには、新しいページを追加するか、デフォルトのドキュメンテーションページを以下のスニペットに置き換えます。

<h1>Documentation</h1>
{% 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 () {
    window.swaggerUi.options['url'] = "{{provider.api_specs.first.url}}";
    window.swaggerUi.load();
  });
</script>

2.3. Swagger UI 2.1.3 から 2.2.10 へのアップグレード

使用している 3scale が Swagger UI 2.1.3 の組み込まれているバージョンである場合、Swagger UI バージョン 2.2.10 にアップグレードできます。

3scale デベロッパーポータルで以前実装されていた Swagger UI 2.1.3 は、Documentation ページに 1 つの {% active_docs version: "2.0" %} Liquid タグがあることが条件です。3scale で Swagger 2.2.10 がサポートされたことに伴い、実装メソッドは複数の Liquid タグ cdn_assetinclude に変わっています。

注記

3scale の以前のバージョンの Swagger UI は、引き続き、従来の active_docs Liquid タグメソッドを使用して呼び出されます。

Swagger UI 2.1.3 を 2.2.10 にアップグレードするには、以下の手順を実施します。

  1. 3scale AMP 管理ポータルにログインします。
  2. Developer PortalDocumentation ページの順に移動するか、Swagger UI 実装を更新するページに移動します。
  3. コードペインで、{% active_docs version: "2.0" %} Liquid タグを cdn_asset Liquid タグの以下のアセットと新しいパーシャル shared/swagger_ui に置き換えます。

    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}
    
    {% include 'shared/swagger_ui' %}
  4. デフォルトでは、Swagger UI は APIs > ActiveDocs に公開された ActiveDocs 仕様を読み込みます。別の仕様を読み込むには、window.swaggerUi.load(); の行の前に以下の window.swaggerUi.options の行を追加します。ここで、<SPEC_SYSTEM_NAME> は読み込む仕様のシステム名です。

    window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";