第3章 3scale への ActiveDocs の追加
3scale は、API のインタラクティブドキュメントを作成するためのフレームワークを提供します。
OpenAPI Specification (OAS) を使用することで、API に機能的なドキュメントを設定することができます。これは、開発者が API を調べ、テストを行い、統合するのに役立ちます。
3.1. 3scale での ActiveDocs の設定
3scale ユーザーインターフェースで ActiveDocs を API に追加すると、API のインタラクティブドキュメントを作成するためのフレームワークが得られます。
前提条件
- API を定義する OpenAPI ドキュメント
-
3scale 2.10 インスタンステナントのクレデンシャル (
tokenまたはprovider_key)
手順
管理ポータルで [your_API_name] → ActiveDocs の順に移動します。3scale では、API のサービス仕様のリストが表示されます。これは最初は空です。
サービス仕様は、必要なだけ追加することができます。通常、各サービス仕様は API のいずれか 1 つに対応しています。たとえば、3scale では、それぞれの 3scale API に仕様があります (Service Management、Account Management、Analytics、および Billing)。
Create a new spec を クリックします。
新しいサービス仕様を追加する場合は、以下を指定します。
- 名前
- システム名。システム名は、デベロッパーポータルからサービス仕様を参照するために必要です。
仕様を公開するかどうかを選択します。公開しない場合には、デベロッパーポータルで新しい仕様は利用できません。
注記新しい仕様を作成するものの、公開しない場合には、今後希望の時期に公開するために利用可能な状態を維持します。
- ご自分だけが使用する目的の説明を追加します。
API JSON 仕様を追加します。
API の仕様は、OpenAPI Specification (OAS) が提案する仕様に従って生成します。本チュートリアルは、API 用に有効な OpenAPI Specification (OAS) 準拠の仕様がすでに用意されていることを前提としています。
最初の ActiveDoc に関する操作
最初の ActiveDoc を追加すると、これが [your_API_name] → ActiveDocs のリストに表示されます。必要に応じて編集、削除、または公開から非公開への切り替えが可能です。これを API から切り離したり、他の API にアタッチしたりできます。Audience → Developer Portal → ActiveDocs の順に移動して、API にアタッチされているかどうかに関わらず、すべての ActiveDocs を確認できます。
サービス仕様に指定した名前 (例: Pet Store) をクリックして、ActiveDocs がどう見えるかをプレビューできます。まだ仕様を公開していない場合でも、この操作を実行できます。
以下は、ActiveDoc の見え方の例です。
