5.2. デベロッパーポータルでの ActiveDocs の公開

本チュートリアルでは、デベロッパーポータルで ActiveDocs を公開すると共に、API ドキュメントを自動化する方法について説明します。

前提条件

  • デベロッパーポータルで ActiveDocs を動作させるには、REST API に対する OpenAPI Specification (OAS) 準拠の仕様が必要です。

手順

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

    注記

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

    <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 behaviour
      // 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>

デベロッパーポータルで ActiveDocs を公開する場合の、他の考慮事項は以下のとおりです。

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

外部ソースから仕様を取得する場合は、以下のように JavaScript コードを変更します。 

$(function () {
 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
 window.swaggerUi.load();
});

仕様のソースを含む行 (window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";) はコメントブロック外であることに注意してください。

検証手順

OpenAPI 仕様 を作成し、3scale に追加 したら、この仕様を公開して、デベロッパーポータルにリンクして、API 開発者が使用できるようにします。