3scale コマンドラインインターフェイス (CLI) は、3scale で管理する API を定義する OpenAPI ドキュメントをインポートするための複数のオプションを提供します。以下は、openapi オプションのヘルプ情報です。

NAME
    openapi - Import API definition in OpenAPI specification

USAGE
    3scale import openapi [opts] -d <dst> <spec>

DESCRIPTION
    Using an API definition format like OpenAPI, import to your 3scale API

OPTIONS
       -d --destination=<value>                   3scale target instance.
                                                  Format: "http[s]://<authentication>@3scale_domain"

 -t --target_system_name=<value>            Target system name

OPTIONS FOR IMPORT
    -c --config-file=<value>                      3scale toolbox
                                                  configuration file
                                                  (default:
                                                  $HOME/.3scalerc.yaml)
    -h --help                                     show help for this command
    -k --insecure                                 Proceed and operate even
                                                  for server connections
                                                  otherwise considered
                                                  insecure
    -v --version                                  Prints the version of this
                                                  command

API 仕様のインポートに関して、3scale の管理者はさまざまなソースを利用することができます。それらの概要を以下の表に示します。ここでは、ファイル名のパス、URL、および stdin から OpenAPI 定義を検出するための使用状況オプションを説明しています。

$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]

$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -

3scale では、OAS 3.0 を使用するための以下のサポートが提供されます。

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

{% 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>

{% 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 2.0 仕様を ActiveDocs に追加し、デベロッパーポータルで表示するには、以下の点を考慮してください。

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>

Swagger UI 2.1.3 を含む 3scale のバージョンを使用している場合は、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_asset と include に変わっています。

管理ポータルで API → ActiveDocs タブに移動します。これにより、サービス仕様のリストが表示されます。サービス仕様がすでに追加されているはずです (Create a service specification を参照)。

デベロッパーポータルで希望する効果を得るためには、適切な名前を適用する必要があります。ActiveDocs API リストの見出しは System name: Description として表示されます。システム名が読み取り専用であるため、JSON 仕様およびその他のフィールドを単純にコピーして仕様を再度作成する必要がある場合があります。

ActiveDocs 2.0 の仕様には、バージョン 1.2 と比較してバージョンに重要な変更がいくつか加えられています。詳細は、Swagger 1.2 から 2.0 への移行ガイド を参照してください。最も重要な変更点は以下のとおりです。

以下のコードスニペットを CMS ページに追加します。ここで、SERVICE_NAME はサービス仕様のシステム名になります。

<h1>Documentation</h1>
<p>Use our live documentation to learn about Echo API </p>
{% active_docs version: "2.0" services: "SERVICE_NAME" %}
<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>

1 つのページに複数の Swagger 仕様を含める場合は、以下のカスタマイズされたスニペットを使用できます。

{% active_docs version: "2.0" services: "oauth" %}



<script type="text/javascript">
  $(function () {
    window.swaggerUi.load(); // <-- loads first swagger-ui
     // do second swagger-ui
     var url = "/swagger/spec/sentiment.json";
    window.anotherSwaggerUi = new SwaggerUi({
      url: url,
      dom_id: "another-swagger-ui-container",
      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
      onComplete: function(swaggerApi, swaggerUi) {
        $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
      },
      onFailure: function(data) {
        log("Unable to Load Sentiment-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });
     window.anotherSwaggerUi.load();
   });
</script>

3scale ユーザーインターフェイスで ActiveDocs を API に追加すると、API のインタラクティブドキュメントを作成するためのフレームワークが得られます。

サービス仕様に指定した名前 (例: Pet Store) をクリックして、ActiveDocs がどのように表示されるかをプレビューできます。まだ仕様を公開していない場合でも、この操作を実行できます。

ActiveDoc は、以下のように表示されます。

ActiveDocs とは OAS のインスタンスのことです。ActiveDocs を使用する場合、独自の OAS サーバーを実行したり、インタラクティブドキュメントのユーザーインターフェイスコンポーネントを扱ったりする必要はありません。インタラクティブドキュメントは、3scale の開発者ポータルから提供され、レンダリングされます。

3scale 2.8 では、OAS 3.0 が導入されましたが、ActiveDocs でのサポートは限定されていました。つまり、自動補完などの ActiveDocs を使用する機能の一部が完全に統合されていないため、新しいアカウントの作成時にデフォルトの 3scale は OAS 2.0 に設定されます。OAS 3.0 および ActiveDocs の詳細は、「3scale での OpenAPI Specification 3.0 の使用」 を参照してください。

すでに OAS 準拠の API 仕様がある場合は、それを開発者ポータルに追加できます。ActiveDocs の設定に関するチュートリアル を参照してください。

3scale では OAS 仕様をさまざまな方法で拡張し、開発者ポータルでのインタラクティブな API ドキュメントに必要な特定の機能に対応しています。以下に例を示します。

オリジナルのソースから仕様を読み取るには、OpenAPI Specification を参照してください。

OAS サイトには、API を定義する OpenAPI ドキュメントの例が複数あります。例を使用して学習したい場合は、OAS API チームが作成した Petstore API の例を参照してください。

Petstore API は非常にシンプルな API です。これは、学習を目的とするものであって、実稼働用ではありません。

Petstore API は 3scale と統合されるため、認証用に別のパラメーターを追加する必要があります。たとえば、ユーザーキー認証方法では、API 利用者はユーザーキーパラメーターを各リクエストのヘッダーに配置する必要があります。その他の認証方法の詳細は、API ゲートウェイの管理の 認証パターン を参照してください。

user_key は、API 利用者により API へのリクエストで送信されます。API 利用者は、3scale 管理者の開発者ポータルでこれらのキーを取得します。キーの受信時に、3scale 管理者は Service Management API を使用して 3scale に対する承認チェックを行う必要があります。

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"

ドキュメントを OAS Petstore のドキュメント のようにする場合は、関連の Petstore swagger.json ファイルのような Swagger 準拠の仕様を作成する必要があります。この仕様をそのまま使用して、ActiveDocs をテストすることができます。ただし、これは実際の API ではないことに注意してください。

OAS は、JSON でエンコードされたハッシュにマッピングするリソース宣言に依存します。Petstore swagger.json ファイルをサンプルとして使用し、各オブジェクトについて説明します。

オブジェクトではないパラメーターは、プリミティブデータタイプを使用します。Swagger では、プリミティブデータ型は JSON スキーマドラフト 4 でサポートされるタイプに基づきます。プリミティブデータ型には追加の file もありますが、3scale では API エンドポイントで CORS が有効な場合にのみ使用されます。CORS が有効になっていると、アップロードは api-docs ゲートウェイを経由せず、拒否されます。

現在、OAS は以下の dataTypes をサポートしています。

API を定義する OpenAPI Specification を設計および編集する際には、以下のツールが役立ちます。

API 認証情報の自動入力は、3scale ActiveDocs の OAS に対する便利なエクステンションです。x-data-threescale-name フィールドには、API 認証モードに応じて以下の値を定義できます。

"parameters": [
  {
    "name": "user_key",
    "in": "query",
    "description": "Your API access key",
    "required": true,
    "schema": {
      "type": "string"
    },
    "x-data-threescale-name": "user_keys"
  }
]

x-data-threescale-name で宣言されたパラメーターの場合、開発者ポータルにログインすると、仕様で設定された値に従って、最新の 5 つのキー、ユーザーキー、アプリ ID またはアプリキーを含むドロップダウンリストが表示されます。したがって、値をコピーして貼り付けることなく、入力を自動入力できます。

この最初の例は、3scale 仕様の OAuth 2.0 クライアント認証情報フローを使用する API に関するものです。この API は任意のパスを受け入れ、リクエストに関する情報 (パス、リクエストパラメーター、ヘッダーなど) を返します。Echo API には、有効なアクセストークンを使用する場合に限りアクセスできまます。API のユーザーは、認証情報 (client_id および client_secret) を交換してアクセストークンを取得するまで、API を呼び出すことができません。

ユーザーが ActiveDocs から API を呼び出せるようにするには、アクセストークンを要求する必要があります。これは単なる OAuth 承認サーバーへの呼び出しなので、OAuth トークンエンドポイント用の ActiveDocs 仕様を作成できます。これにより、ActiveDocs 内からこのエンドポイントへの呼び出しが可能になります。この例のクライアント認証情報フローの場合、Swagger JSON 仕様は以下のようになります。

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "OAuth for Echo API",
    "description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "red-hat-sso-instance.example.com",
  "basePath": "/auth/realms/realm-example/protocol/openid-connect",
  "schemes": [
    "http"
  ],
  "paths": {
    "/token": {
      "post": {
        "description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
        "operationId": "oauth",
        "parameters": [
          {
            "name": "client_id",
            "description": "Your client id",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "client_secret",
            "description": "Your client secret",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "grant_type",
            "description": "OAuth2 Grant Type",
            "type": "string",
            "default": "client_credentials",
            "required": true,
            "in": "query",
            "enum": [
                "client_credentials",
                "authorization_code",
                "refresh_token",
                "password"
            ]
          }
        ]
      }
    }
  }
}

リソースオーナー OAuth フローでは、ユーザー名とパスワードのパラメーターおよびアクセストークンを発行するために必要なその他のパラメーターを追加する必要があります。このクライアント認証情報フローの例では、client_id と client_secret (サインイン済みユーザーの 3scale の値を代入可能)、ならびに grant_type を送信しています。

次に、Echo API の ActiveDocs 仕様で、client_id と client_secret の代わりに access_token パラメーターを追加します。

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "Echo API",
    "description": "A simple API that accepts any path and returns information about the request",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "echo-api.3scale.net",
  "basePath": "/v1/words",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{word}.json": {
      "get": {
        "description": "This operation returns information about the request (path, request parameters, headers, etc.),
        "operationId": "wordsGet",
        "summary": "Returns the path of a given word",
        "parameters": [
          {
            "name": "word",
            "description": "The word related to the path",
            "type": "string",
            "in": "path",
            "required": true
          },
          {
            "name": "access_token",
            "description": "Your access token",
            "type": "string",
            "in": "query",
            "required": true
          }
        ]
      }
    }
  }
}

その後は、通常どおり開発者ポータルに ActiveDocs を含めることができます。この場合、OAuth エンドポイントが最初に表示されるよう順番を指定する必要があるため、以下のようになります。

{% active_docs version: "2.0" services: "oauth" %}





<script type="text/javascript">
  $(function () {
    window.swaggerUi.load(); // <-- loads first swagger-ui

    // do second swagger-ui

    var url = "/swagger/spec/echo-api.json";
    window.anotherSwaggerUi = new SwaggerUi({
      url: url,
      dom_id: "another-swagger-ui-container",
      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
      onComplete: function(swaggerApi, swaggerUi) {
        $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
      },
      onFailure: function(data) {
        log("Unable to Load Echo-API-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });

    window.anotherSwaggerUi.load();

  });
</script>

このチュートリアルでは、開発者ポータルで ActiveDocs を公開すると共に、API ドキュメントを自動化する方法について説明します。

開発者ポータルで ActiveDocs を公開する場合の、他の考慮事項は以下のとおりです。

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

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

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

3scale は認証するユーザーに関する情報を保持しないため、OAuth 2.0 を使用して 3scale と統合するためには、お客様側でユーザー認証を処理する必要があります。そのためには、APIcast がアプリケーションの承認のためにユーザーを送信できるページの URL を提供する必要があります。ユーザーを正しく識別し、認証できるように、このページはログインの背後になければなりません。ユーザーが認証され、アプリケーションが承認されたら、ユーザーからの承認付与の結果により APIcast にリダイレクトする必要があります。

APIcast がユーザーを承認 URL にリダイレクトすると、リクエストと共に以下のパラメーターが送信されます。

ユーザーが認証に成功してアプリケーションを承認すると、承認ページは APIcast のエンドポイントにリダイレクトするはずです。デフォルトでは、これは /callback にありますが、必要に応じて APIcast 設定ファイル内で簡単に変更することができます。

この設定方法を確認します。

インストールを続行するには、API を設定しメソッドおよびエンドポイントを定義する基本的な APIcast インテグレーションとほとんど同じ手順に従う必要があります。これらの手順は、Installing APIcast を参照してください。また、以下の手順に従う必要があります。

7.2.1. ステップ 1: インテグレーション設定の編集

OAuth は現在 Hosted APIcast では利用できないため、以下のスクリーンショットのとおり、Production Deployment Option を自己管理型ゲートウェイに設定する必要があります。

同じページで、Authentication を OAuth 2.0 に設定する必要もあります。

NGINX に精通している場合は、APIcast をローカルで稼働するのに時間がかかりません。NGINX インストールには Lua プラグインがなければなりません。また、OAuth 2.0 付与タイプによっては、Redis もサーバーにインストールされている必要があります。

NGINX に精通していない場合には、OpenResty をインストールすることを推奨します。これは基本的に標準 NGINX コアと組み込む必要のあるほとんどすべてのサードパーティー NGINX モジュールがバンドルされた素晴らしい Web アプリケーションです。

sudo apt-get install libreadline-dev libncurses5-dev libpcre3 libpcre3-dev libssl-dev perl
sudo apt-get build-dep nginx

wget http://agentzh.org/misc/nginx/ngx_openresty-VERSION.tar.gz
tar -zxvf ngx_openresty-VERSION.tar.gz
cd ngx_openresty-VERSION/

./configure --prefix=/opt/openresty --with-luajit --with-http_iconv_module -j2

make
make install

tar zxvf  redis-VERSION.tar.gz
cd redis-VERSION
make
sudo make install

sudo ./utils/install_server.sh

sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf

sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf -s stop

7.3.6. ステップ 6: OAuth フローのテスト

API が OAuth をサポートしていることをテストする最善の方法は、Google の OAuth Playground (https://developers.google.com/oauthplayground) を使用することです。

このテストに使用するアプリケーションのリダイレクト URL を、Google OAuth Playground の URL https://developers.google.com/oauthplayground に設定する必要があります。

これで、以下のスクリーンショットに示すように、設定を入力することができます。

承認およびトークンエンドポイントの URL は、APIcast インスタンスからの URL です。スコープに、アプリケーションのアプリケーションプラン名を追加します (例: デフォルト)。

Authorize API をクリックすると、ログイン URL にリダイレクトされます。次に、アプリケーションのユーザーアカウントにログインし、アプリケーションを承認します。完了すると、認可コードと共に Google OAuth Playground にリダイレクトされます。これをアクセストークンと交換します。これで、API の保護されたエンドポイントを呼び出すアクセストークンを取得しました。

これで API にリクエストを行うことができます。ここで、API バックエンドのホスト名 (この例では echo-api.3scale.net) を APIcast インスタンスのホスト名で置き換え、access_token パラメーターを追加します。以下に例を示します。

curl -X GET "http://YOUR_APICAST_HOST/read?access_token=YOUR_ACCESS_TOKEN"

これで API が 3scale と統合されました。