第2章 OpenAPI Specification の設定方法
OpenAPI Specification が 3scale と連携するには、使用するバージョン用に正しく設定する必要があります。
前提条件
- API を定義する OpenAPI ドキュメント
-
3scale 2.11 インスタンステナントのクレデンシャル(
tokenまたはprovider_key)。
2.1. 3scale での OpenAPI Specification 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 を使用するデベロッパーポータルの設定
このスニペットには、新しいバージョンの 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>テンプレートを更新するには、デフォルトのドキュメンテーションページを「OAS 3.0 を使用するデベロッパーポータルの設定」に含まれるスニペットに置き換えます。