第4章 OAS 仕様の作成

本章は、REST API 用に OpenAPI Specification (OAS) 準拠の仕様を作成するのに役立ちます。この仕様は、デベロッパーポータルで ActiveDocs を動作させるのに必要です。コードを読むだけであれば、すべての例は OAS Petstore のソースコード例 に記載されています。

4.1. OpenAPI Specification (OAS) について

3scale ActiveDocs は、Swagger と呼ばれる RESTful Web サービスの仕様をベースにしています (Wordnik より)。この例は、拡張された OpenAPI Specification の Petstore の例 をベースにしており、すべての仕様データを OpenAPI Specification 2.0 の仕様ドキュメント から引用しています。

OAS は単なる仕様ではありません。これに関連するあらゆる機能のフレームワークも提供します。

  1. 複数の言語 (NodeJS、Scala、その他) によるリソース仕様のサーバー
  2. 仕様ファイルを使用して開発者を引き付ける UI を生成する、さまざまな HTML/CSS/Javascripts アセット
  3. Swagger 準拠サーバーからクライアントライブラリーを自動的に生成することのできる、OAS codegen プロジェクト。数多くの現代的な言語によるクライアント側のライブラリー作成をサポートします。

4.2. 3scale ActiveDocs と OAS

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

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

前提条件

  • デベロッパーポータルで使用するテンプレートが、管理ポータルで指定した OAS バージョンと同じものであることを確認します。

手順

  1. OAS に準拠する API 仕様を構築します。
  2. 管理ポータルに仕様を追加します。

以下の手順により、インタラクティブドキュメントが利用可能になります。開発者は、デベロッパーポータルを通じて API に対するリクエストを行うことができます。

すでに OAS 準拠の API 仕様がある場合は、それをデベロッパーポータルに追加できます (ActiveDocs の設定に関するチュートリアル を参照)。

3scale では OAS 仕様をさまざまな方法で拡張し、独自のインタラクティブな API ドキュメント作成で必要となった特定の機能に対応しました。

  • API キーの自動入力
  • CORS 非対応 API への呼び出しを許可する OAS プロキシー

4.3. API 仕様の作成

まず、オリジナルのソースから仕様を確認することを推奨します。OAS 仕様 を参照してください。

OAS サイトには、仕様の例が複数あります。例を使って学習したい場合は、OAS API チームが作成した Petstore API の例に従うことができます。

4.3.1. Petstore API の例を使った学習

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

Petstore API は、4 つのメソッドで構成されています。

  • GET /api/pets: システムからすべてのペットを返す
  • POST /api/pets: ストアに新しいペットを作成する
  • GET /api/pets/{id}: ID に基づき 1 つのペットを返す
  • DELETE /api/pets/{id}: ID に基づき 1 つのペットを削除する

Petstore API は 3scale と統合されるため、認証用に別のパラメーターを追加する必要があります。たとえば、User Key 認証方法を使用すると、パラメーターがヘッダーに送信されます。その他の認証方法の詳細は、『API ゲートウェイの管理』の「認証パターン」を参照してください。

以下のパラメーターを追加する必要があります。

user_key: {user_key}

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

開発者にとって、cURL 呼び出しで表される API のドキュメントは、以下のようになります。

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 ではないことに注意してください。詳細は、次のセクションで説明します。

4.3.2. OAS 仕様の詳細について

OAS 仕様は、JSON でエンコードされたハッシュにマッピングするリソース宣言に依存します。Petstore swagger.json ファイルを例にして、ステップごとに手順を説明します。

4.3.2.1. OAS オブジェクト

これは API 仕様のルートドキュメントオブジェクトです。最上位レベルのフィールドをすべて一覧表示します。

警告

ホストは、IP アドレスではなくドメインでなければなりません。3scale は、デベロッパーポータルに対して行われたリクエストをプロキシーとしてホストに中継し、結果をレンダリングします。そのためには、セキュリティー上の理由から、ホスト および basePath エンドポイントがホワイトリストに登録されている必要があります。宣言できるのは、ご自分のホストだけです。API プロバイダーが自身に属さないドメインを中継していることが確認された場合、3scale は API プロバイダーのアカウントを終了する権利を有します。つまり、ローカルホストまたはその他のワイルドカードドメインは機能しません。

4.3.2.2. Info オブジェクト

Info オブジェクトは API に関するメタデータを提供します。これは ActiveDocs ページに提示されます。

4.3.2.3. paths オブジェクト

paths オブジェクトは、個々のエンドポイントへの相対パスを保持します。パスが basePath に追加され、完全な URL となります。ACL の制約により、パスは空である場合があります。

オブジェクトではないパラメーターは、プリミティブデータタイプを使用します。Swagger では、これらは JSON スキーマドラフト 4 でサポートされるデータタイプに基づきます。プリミティブデータタイプには「file」もありますが、これが機能するのは、API エンドポイントで CORS が有効な場合 (したがって、アップロードは api-docs ゲートウェイを経由しない) のみです。そうでない場合は、ゲートウェイレベルで停止します。

サポートされるデータタイプ

現在、OAS は以下の データタイプ をサポートしています。

  • 整数型フォーマット: int32 および int64。どちらのフォーマットも符号付きです。
  • 数値型フォーマット: float および double
  • プレーン文字列
  • 使用できる形式の文字列: バイト、日付、日時、パスワード、およびバイナリー
  • boolean

4.3.3. OAS の設計および編集ツール

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

  • オープンソースの Apicurio Studio を使用すると、Web ベースのアプリケーションで OpenAPI ベースの API を設計および編集することができます。Apicurio Studio では設計ビューを利用することができるので、OpenAPI 仕様に関する詳細な知識は必要ありません。習熟したユーザーは、ソースビューを使用して直接 YAML または JSON で編集することができます。詳細は、「Getting Started with Apicurio Studio」を参照してください。

    Red Hat では、Apicurio Studio の軽量バージョンである API Designer も提供しています。このツールは、Fuse Online on OpenShift に含まれています。詳細は、『Developing and Deploying API Provider Integrations』を参照してください。

  • JSON 表記を十分に理解している場合は、JSON Editor Online が便利です。JSON を縮小化する整形フォーマットを使用することができ、JSON オブジェクトブラウザーが提供されます。
  • Swagger Editor を使用すると、YAML で書かれた OAS API 仕様をブラウザーで作成および編集し、リアルタイムでプレビュー表示することができます。有効な JSON 仕様を生成することもできます。これを後から 3scale 管理ポータルにアップロードすることができます。機能が限定された ライブデモ バージョンを使用することや、独自の OAS エディターをデプロイすることができます。

4.3.4. ActiveDoc の API キー自動入力

API キーの自動入力は、3scale ActiveDocs の OAS 仕様に対する有用な拡張機能です。parameters セクションで、API 認証モードに応じて、x-data-threescale-name フィールドに以下の値を定義できます。

  • user_keys: API キー認証のみを使用するサービスのアプリケーションのユーザーキーを返します。
  • app_ids: アプリケーション ID/アプリケーションキーを使用するサービスのアプリケーションの ID を返します (後方互換のために、OAuth と OpenID Connect もサポートされています)。
  • app_keys: アプリケーション ID/アプリケーションキーを使用するサービスのアプリケーションのキーを返します (後方互換のために、OAuth と OpenID Connect もサポートされています)。

API キー認証の例

API キー認証のみの場合に "x-data-threescale-name": "user_keys" を使用する例を以下に示します。

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

アプリケーション ID/アプリケーションキー認証の例

アプリケーション ID/アプリケーションキー認証モードの場合には、アプリケーション ID を表すパラメーターには "x-data-threescale-name": "app_ids" を指定し、アプリケーションキーを表すパラメーターには "x-data-threescale-name": "app_keys" を指定します。

パラメーターを宣言していると、ActiveDocs は自動的に、ActiveDocs ユーザーにデベロッパーポータルにログインしてキーを取得するよう求めます (以下のスクリーンショットを参照)。

Auto-fill when not logged-in

ユーザーがすでにログインしている場合は、ActiveDocs は該当する可能性のある直近 5 つのキーを表示します。これにより、キーをコピー/ペーストせずにすぐテストすることができます。

Auto-fill when logged-in
注記

x-data-threescale-name フィールドは OAS 仕様の拡張機能で、ActiveDocs 以外のユースケースでは無視されます。