Swagger の普及活動の一環として、Swagger チームは先日 SwaggerHub を立ち上げました。これは、主要な Swagger ツール (UI、エディタ、コードジェネレータ、バリデータ) を統合し、Swagger とそのツールをより簡単に利用開始できることを目指した共同プラットフォームです。この投稿では、SwaggerHub によって公開されている対応する API に焦点を当てます。この API を使用すると、SwaggerHub レジストリで Swagger 定義を検索、取得、作成、更新できます。これにより、以下のことが可能になります。
- SwaggerHub からの Swagger 定義の検索と取得を既存の API ツールに統合する
- Swagger 定義を SwaggerHub に直接保存する
SwaggerHub API は https://app.swaggerhub.com/apis/swagger-hub/registry-api/ で利用でき、その Swagger 2.0 定義は https://swaggerhub.com/api/swagger-hub/registry-api で利用できます。
SwaggerHub API 識別子
API 自体に入る前に、SwaggerHub が API をどのように識別するかを簡単に見てみましょう。この「スキーム」は、API と SwaggerHub の両方で広く使用されています。
SwaggerHub の各 Swagger 定義は、以下の値によって識別されます。
- owner - API を所有するアカウント
- api - 所有者アカウント下の API の一意の識別子
- version - 一意のバージョン識別子
API と SwaggerHub アプリケーションの両方で、これらは上記の順序でパスセグメントとして結合され、SwaggerHub およびその API の API に直接リンクできます。
https://swaggerhub.com/api/{owner}/{api}/{version}
または
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
SwaggerHub API の場合、これらのエンドポイントは次のとおりです。
最後にバージョンを省略すると、わずかに異なる結果が得られます。
- Web バージョンでは、API のデフォルトバージョンが表示されます (API 設定で設定可能)。
- API バージョンでは、API のすべてのバージョンの apis.json リストが返されます。
apis.json
SwaggerHub API への GET コールの多くは、apis.json 形式で API のリストを返します。例えば、https://api.swaggerhub.com/apis/swagger-hub/registry-api は SwaggerHub API のすべてのバージョンのリストを返します。apis.json 形式については、apisjson.org の Web サイトで読むことができます。上記のリストの各項目には、SwaggerHub に固有のカスタム "X-??" プロパティが多数含まれています。
- X-Version: 対応する API の SwaggerHub におけるバージョン
- X-Created: バージョンが SwaggerHub で作成された日時
- X-Modified: バージョンが SwaggerHub で最後に変更された日時
- X-Published: この API バージョンが SwaggerHub で「公開」されたかどうか (最終状態にあることを示す)
この特定のリストについては、(執筆時点では) 結果に 3 つの項目が得られるはずです。バージョン 1.0.0、1.0.1、1.0.2 と、対応するメタデータです。
認証
SwaggerHub API によって公開されているリソースのほとんどは認証トークンを必要としません。現在必要なのは、指定されたバージョンを作成/更新する /apis/{owner}/{api} への POST のみです (詳細については後述)。このコールを行うには、SwaggerHub UI から以下の手順で取得できる API-Key を含む「Authorization」HTTP ヘッダーを提供する必要があります。
- 右上のメニューで「設定」を選択します
- 左側で「API-Key」を選択します
- 「API-Key の作成」をクリックします
このキーを使用すると、アカウントで新しい/更新された API を投稿できるだけでなく、検索や API リストにいくつかの追加機能も追加されます。
- 認証されたユーザーが特定の API に対して持つロール (owner、edit、view) を示す追加の X-UserRole apis.json プロパティ
- API 検索コールにクエリ引数として filter=user を指定する可能性。これにより、認証されたユーザーが所有者またはコラボレーターとしてアクセスできる API のみが返されます (X-UserRole プロパティは「owner」または「edit」になります)。
SwaggerHub レジストリの検索
では、早速始めましょう。SwaggerHub API のベースリソースは https://api.swaggerhub.com/apis です。
このリソースは、SwaggerHub レジストリ内のすべての公開 API のページ分割されたリストを返します (執筆時点ではすべての API が公開されていますが、近い将来変更される予定です)。Swagger 定義が示すように、フィルタリングにはいくつかのクエリ引数が利用できます。
- query: すべての API の owner、name、swagger.info.title、swagger.info.description を検索します
- tag: 指定されたタグを持つ API のみを返します
- state: 指定された状態の API のみを返します
- page and limit: ページング
- sort and order: ソートと順序 (!)
例えば、公開されている金融 API を見つけたい場合は、次のように呼び出します。
執筆時点では、1 つの API が返されます。やった！
特定の所有者の API のみに検索を絞り込みたい場合は、swagger.json に記載されているように、それをパスに追加します。
上記の API コールから得られる結果は、SwaggerHub UI で表示されるものとまったく同じであることに気づくかもしれません。これは、SwaggerHub が内部ですべての API 検索/取得/更新機能にこの同じ API を使用しているためです。
検索結果の API バージョン
ご覧のとおり、{owner}/{api} ごとに 1 つのエントリのみが返され、その API の各バージョンのエントリは返されません。API のデフォルトバージョンは、X-Version apis.json プロパティに、その swagger.json へのリンクとともに、Swagger プロパティで返されます。X-Versions プロパティも追加され、その API のすべてのバージョンのコンマ区切りのリストが含まれます。公開されているバージョンにはアスタリスクが付けられます。
例えば、fehguy のホームオートメーションプロジェクトには、上記のリストに以下のプロパティがあります。
これは、デフォルトバージョンが 1.0.0 に設定されているが、他のバージョン (1.0.1 および 1.0.2) も利用可能であることを示しています。また、公開されている唯一のバージョンが 1.0.1 であることも示しています。
パスに API ID を追加すると、その API のすべてのバージョンが表示されます。例えば、以下は SwaggerHub Registry API のすべてのバージョンを返します。
https://api.swaggerhub.com/apis/swagger-hub/registry-api
API 定義の取得
API 定義の取得は、上記で示されているように簡単です。JSON または YAML 形式 (デフォルトは JSON - YAML バージョンには Accept ヘッダーを「application/yaml」に設定) で Swagger 定義を取得するには、エンドポイント https://api.swaggerhub.com/apis/{owner}/{api}/{version} を使用します。特定の形式を直接指定したい場合は、エンドポイントに swagger.json または swagger.yaml を追加できます。例えば、SwaggerHub 定義の JSON バージョンは https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.0/swagger.json で利用できます。
API 定義の作成 / 更新
上記で説明したように API-Key を設定したら、SwaggerHub レジストリで Swagger 定義を作成および更新する準備が整いました。実際の Swagger 2.0 定義を https://api.swaggerhub.com/apis/{owner}/{api} に POST するだけです。
以下のルールが適用されます。
- API を更新/作成できるのは、ご自身のアカウント (つまり、ご自身のユーザー名を所有者とするもの) の下のみです。
- 今のところ、ファイルには構文的に有効な YAML または JSON コンテンツが含まれている必要があります。
- API のバージョンは、Swagger 定義の version プロパティから抽出されます。これが欠落しているか無効な場合、定義は拒否されます。
- そのバージョンで API バージョンが既に存在する場合、新しい定義で更新されます (ただし、そのバージョンが公開されている場合は、更新は拒否されます)。
以上です！
シンプルで簡単ですよね？上記の通りブラウザで直接 API を操作することもできます (ほとんどの呼び出しは GET 呼び出しなので)。または、SwaggerHub に統合された Swagger-UI を https://swaggerhub.com/api/swagger-hub/registry-api/1.0.0/ui で使用することもできます (末尾の「ui」に注目してください。インターフェースの Swagger-UI タブが自動的に選択されます)。
さあ、皆さんの統合事例で私たちを驚かせてください。https://swagger.dokyumento.jp で共有したいと考えています。実際の統合例を見たい場合は、https://github.com/SmartBear/readyapi-swaggerhub-plugin で入手可能な Ready! API SwaggerHub プラグインのソースコードをご覧ください。
Swagger オン！