第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"> </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 を使用するデベロッパーポータルの設定」 に含まれるスニペットに置き換えます。