2.3. API 仕様の作成
まず、オリジナルのソース OAS 仕様 から、オリジナルの仕様を確認することを推奨します。
OAS サイトには、仕様の例が複数あります。例を使って学習したい場合は、OAS API チームが作成した Petstore API の例に従うことができます。
2.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 API Management と統合されます。このため、認証用に新たなパラメーターを追加する必要があります。たとえば、ユーザーキー認証方法では、このパラメーターはヘッダーで送信されます。他の認証方法については、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 ではないことに注意してください。詳細は、次のセクションで説明します。
