5.2. 開発者ポータルでの ActiveDocs の公開

前提条件

• 開発者ポータルで ActiveDocs を動作させるには、REST API に対する OpenAPI Specification (OAS) 準拠の仕様が必要である。

手順

• 以下のスニペットを、開発者ポータルの任意のページのコンテンツに追加します。3scale 管理ポータルからこの操作を行う必要があります。

  注記

  SERVICE_NAME はサービス仕様のシステム名 (この例では pet_store) です。

  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 2.0 を使用した開発者ポータルの設定

  <h1>Documentation</h1>
  <p>Use our live documentation to learn about Echo API</p>
  {% active_docs version: "2.0" services: "SERVICE_NAME" %}
  {% 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 () {
      {% comment %}
        // you have access to swaggerUi.options object to customize its behavior
        // such as setting a different docExpansion mode
        window.swaggerUi.options['docExpansion'] = 'none';
        // or even getting the swagger specification loaded from a different url
        window.swaggerUi.options['url'] = "http://petstore.swagger.io/v2/swagger.json";
      {% endcomment %}
      window.swaggerUi.load();
    });
  </script>

• 1 ページに指定できるサービスは 1 つだけです。複数の仕様を表示する場合は、別々のページで表示することが最善の方法となります。
• このスニペットには jQuery が必要ですが、これはデフォルトで開発者ポータルのメインレイアウトに含まれています。jQuery 依存関係をメインレイアウトから削除する場合は、ActiveDocs を含むページでこの依存関係を追加する必要があります。
• 管理ポータルで Liquid タグが有効になっていることを確認します。
• OAS 2.0 の Liquid タグで使用されるバージョン {{ '{% active_docs version: "2.0" ' }}%} は、Swagger 仕様のバージョンに対応している必要があります。