この記事では、SwaggerHub の簡単な概要と、SwaggerHub を使用して API 定義を作成して公開する方法を説明します。
準備
以下のものが必要になります。
- SwaggerHub アカウント (お持ちでない場合は こちらから作成してください)
- API に関する基本的な知識
SwaggerHub とは?
SwaggerHub は、パブリック API、内部プライベート API、マイクロサービスなど、API を設計するためのオンライン プラットフォームです。SwaggerHub の基本原則は、「Design First, Code Later (設計してからコーディング)」です。つまり、API、そのリソース、操作、データ モデルをレイアウトすることから始め、設計が完了したらビジネス ロジックを実装します。
API 定義は OpenAPI (旧 Swagger) または AsyncAPI 形式で記述します。これらは SwaggerHub クラウドに保存され、GitHub や Amazon API Gateway などの外部システムと同期できます。また、SwaggerHub 上でチームとコラボレーションしたり、API の進化に合わせて複数のバージョンを管理することも可能です。
この記事では、OpenAPI (REST) の例を説明しますが、AsyncAPI でもプロセスは同じです。
MyHub ページ
SwaggerHub にログインすると、
MY hub ページにアクセス可能なすべての API のリストが表示されます。このリストには、あなたが作成した API と、コラボレーションのため招待された API の両方が含まれます。
SwaggerHub で既存の API を検索するには、左側のサイドバーで 
をクリックしてアクセスできる検索ページを使用します。これにより、他の SwaggerHub ユーザーが開発した素晴らしいパブリック API を見つけることができます。検索構文については、「SwaggerHub の検索」を参照してください。
特定の API を表示するには、リストでその API をクリックします。
SwaggerHub の API ページでは、OpenAPI 定義の YAML コードと、それをベースに生成されたリファレンス形式の API ドキュメントが分割表示されます。ユーザーは、API ドキュメントを使用して、ブラウザーで API 呼び出しを直接テストできます。左側のナビゲーション パネルには、API で定義された操作とモデルのリストが表示され、YAML コード内の対応する場所にジャンプできます。パネルのサイズを変更するには、パネル間のスプリッターをドラッグします。
次のステップは、API のデザイナーとコンシューマーでは異なります。適切なほうにお進みください。
- API デザイナーの場合: API の作成
- API コンシューマーの場合: リソース ファイルの確認とコメントの追加
SwaggerHub を使用したサンプル API の作成
API デザイナーにとって、SwaggerHub を理解する最良の方法はサンプル API を作成することです。早速作成してみましょう。サーバーの構成について心配する必要はありません。ここでは、API の設計に注目して説明します。
ステップ 1: API の作成
左側のサイドバーで 
をクリックして、[Create New API] を選択します。
以下の画像に示すように API 情報を入力します。
-
[Specification] フィールド: 仕様の形式 (OpenAPI 3.0.0、OpenAPI 2.0、または AsyncAPI 2.x) を指定します。この例では、OpenAPI 3.0.0 を選択します。
-
[Template] フィールド: テンプレートを指定します。Petstore など、事前定義されたテンプレートが用意されていますが、ここでは空の API (テンプレートなし) から始めましょう。
-
[Name] フィールド: API の名前を指定します。この例では、sample と入力します。
-
[Version] フィールド: API のバージョンを指定します。この例では、1.0.0 と入力します。
-
[Title] フィールド: API のタイトルを指定します。この例では、Sample API と入力します。
-
[Description] フィールド: API の説明を入力します。任意の説明を入力してください。
-
[Auto Mock API] スライダー: この例では、OFF になっていることを確認してください。
ON にすると、SwaggerHub は自動的にベース パス (https://virtserver.swaggerhub.com/{owner}/{api}/{version}) で API モックを作成します。これにより、API の設計時に API をテストできるようになり、開発者は API 機能が実装されるまで待つことなくクライアント アプリケーションの開発に取りかかることができます。
詳細は、「API Auto Mocking」を参照してください。
[Create API] をクリックします。SwaggerHub エディターが開き、入力した API メタデータが自動で追加されます。
各 API 定義は API バージョン (この例では、openapi: 3.0.0) で始まります。
openapi: 3.0.0
続く info セクションには、API のタイトル、説明、バージョンなど、API メタデータが含まれます。連絡先、ライセンス情報、その他の詳細を含めることもできます。
info: title: Sample API version: 1.0.0 description: This is a sample API.
paths セクションでは、API の操作を定義します。これは、後で入力します。
paths: {}
ステップ 2: サーバー情報の追加
次に、API サーバーのアドレスと API 呼び出しのベース URL を定義する必要があります。API が https://api.example.com/v1 にある場合、次のように記述できます。
servers: - url: https://api.example.com/v1
これを info と paths の間に追加します。
ステップ 3: GET 操作の定義
この例で作成する API は、ユーザー リストを管理するためのもので、各ユーザーには ID があり、API は ID を受け取ってユーザーを返す操作が必要であるとします。この操作は、次のような GET リクエストになります。
GET /users/3 GET /users/15
Swagger を使用して、この GET 操作を次のように記述できます。/users/{userId} の {userId} は、パス パラメーター、つまり変わる可能性のある URL コンポーネントを示しています。
paths:
/users/{userId}:
get:
summary: Returns a user by ID
responses:
'200':
description: OK
上記のコードをエディターに貼り付けて、paths: {} 行を置換します。次のようになります。
仕様を編集すると、SwaggerHub は自動的に右側のプレビューを更新します。
ステップ 4: パラメーターの定義
API 操作 GET /users/{userId} には、ユーザーの ID を指定する userId パラメーターがあります。仕様でこのパラメーターを定義するには、次のように parameter セクションを追加します。
paths:
/users/{userId}:
get:
summary: Returns a user by ID
parameters:
- name: userId
in: path
required: true
description: The ID of the user to return
schema:
type: integer
responses:
'200':
description: OK
このコードでは、name (URL パスで使用したものと同じ)、type、description、および required (必須かどうか) パラメーターを指定します。in: path はパラメーターを、クエリ文字列パラメーター (GET /users?id=15) ではなく、URL パスの一部 (GET /users/15) として渡します。
parameters セクションを追加すると、新しく追加したパラメータ情報を反映するようにプレビューが更新されます。
ステップ 5: レスポンスの定義
次に、API 呼び出しに対して可能な responses を記述する必要があります。レスポンスは、HTTP ステータス コード、説明、任意で指定可能な schema (レスポンス ボディのデータ モデルがある場合) によって定義されます。
この例では、GET /users/{userId} 呼び出しに成功したら、HTTP ステータス 200 と次の JSON オブジェクトを返すようにします。
{
"id": 42,
"name": "Arthur Dent"
}
このレスポンスを記述するには、200 レスポンスの下に次のように content セクションを追加します。content セクションでは、レスポンスに JSON データ (application/json) が含まれることを指定します。schema 要素には、返される JSON オブジェクトのプロパティなど、レスポンス ボディの構造を記述します。
paths:
/users/{userId}:
get:
...
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
また、API 呼び出しによって返される可能性のあるさまざまなエラー コードを記述することもできます。
responses:
...
'400':
description: The specified user ID is invalid (e.g. not a number)
'404':
description: A user with the specified ID was not found
完全な仕様は次のようになります。
ステップ 6: API の公開
API が完成したので、公開してみましょう。公開することで、API が安定した状態にあり、設計どおりに動作し、アプリケーションで利用可能なことを他の人に知らせます。この例では、実際に実装せずに API 仕様を設計するので、サーバーの構成について心配する必要はありません。
API を公開するには、API バージョンの横にあるドロップダウンをクリックし、 
をクリックします。
これで、最初の API が SwaggerHub に公開されました。ブラウザーのアドレス バーからアドレスをコピーして、他の人と共有できます。これはパブリック API であるため、リンクを持っている人は誰でも閲覧でき、SwaggerHub の検索結果にも表示されます。ご利用の SwaggerHub プランで許可されている場合は、API をプライベートにすることができます。
公開された API は読み取り専用になり、API が再度非公開になった場合のみ編集できることに注意してください。description テキストを編集したり、タイプミスを修正する必要がある場合は、API を一時的に非公開にしても問題ありません。ただし、新しい操作やパラメーターなどの重大な変更の場合は、代わりに SwaggerHub エディターの [Add Version] コマンドを使用して新しいバージョンを開始する必要があります。SwaggerHub では API 仕様の複数のバージョンを維持できるため、公開済みのバージョン (「運用」バージョン) をそのまま維持しながら、次の API バージョンに取り組むことができます。
SwaggerHub エディターのその他の機能
SwaggerHub エディターは単なるエディターではなく、API 仕様を管理し、ワークフローに統合するためのツールを提供します。次の機能を利用できます。
- [Settings] メニューでは、API の名前変更、フォーク、別のオーナーへの譲渡を行うことができます。
- [Export] メニューでは、実装に必要な API のサーバー コードとクライアント コードを生成できます。また、OpenAPI 定義を YAML または JSON 形式でダウンロードすることもできます。
リソース ファイルの確認
API の作成/更新に必要な権限を持たないコンシューマーは、SwaggerHub を使用して読み取り専用モードでリソース ファイル (API、テンプレート、ドメイン) にアクセスできます。リソース ファイルを確認するには、メイン画面でそのファイルをクリックするだけです。
API 定義を開いたら、内容を確認できます。画面の見方がわからない場合は、チュートリアルを参照してください。
システム管理者が許可している場合は、リソース ファイルにコメントを挿入できます。
SwaggerHub 製品に関する詳細、無料評価版は、こちら。
この資料は、SmartBear の Web サイトで公開されている「Basics of SwaggerHub」の日本語参考訳です。
