第3章 3scale への仕様の追加

本章では、API に ActiveDocs を設定する手順について説明します。

3scale は、API のインタラクティブドキュメントを作成するためのフレームワークを提供します。

OpenAPI Specification (OAS) を使用することで、API に機能的なドキュメントを設定することができます。これは、開発者が API を調べ、テストを行い、統合するのに役立ちます。

3.2. サービス仕様の作成

新しいサービス仕様を追加する場合は、以下の項目を指定する必要があります。

  • 名前
  • システム名 (デベロッパーポータルからサービス仕様を参照するために必要)
  • 仕様を公開するかどうか
  • 説明 (内部的にのみ使用される)
  • API JSON 仕様 (以下の図を参照)

API JSON 仕様は、ActiveDocs の「秘密の成分」です。

API の仕様は、OpenAPI Specification (OAS) が提案する仕様に従って生成する必要があります。本チュートリアルは、API 用に有効な OpenAPI Specification (OAS) 準拠の仕様がすでに用意されていることを前提としています。

Create a service specification for ActiveDocs

3.3. 最初の ActiveDoc に関する操作

最初の ActiveDoc を追加すると、これが [your_API_name] → ActiveDocs のリストに表示されます。必要に応じて編集、削除、または公開から非公開への切り替えが可能です。また、これを API から切り離したり、他の API にアタッチしたりできます。Audience → Developer Portal → ActiveDocs の順に移動して、(API にアタッチされているかどうかに関わらず) すべての ActiveDocs を確認できます。

List of Service specifications for ActiveDocs

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

以下は、ActiveDoc の見え方の例です。

ActiveDocs new specification view