API デザインツール API Hub for Design を使ってみよう！

この記事では、API Hub for Design の簡単な概要と、API Hub for Design を使用して API 定義を作成して公開する方法を説明します。

準備
API Hub for Design とは?
My API 画面
API Hub for Design を使用したサンプル API の作成
リソースファイルの確認

準備

以下のものが必要になります。

SmartBear ID アカウント (お持ちでない場合は、こちらから作成してください)
API に関する基本的な知識

API Hub for Design とは?

API Hub for Design は、パブリック API やプライベート API など、API をデザインするためのオンラインプラットフォームです。API Hub for Design の基本原則は、「Design First, Code Later (デザインしてからコーディング)」です。つまり、API、そのリソース、操作、データモデルをレイアウトすることから始め、デザインが完了したらビジネスロジックを実装します。

API 定義は OpenAPI (旧 Swagger) または AsyncAPI 形式で記述します。これらは API Hub for Design クラウドに保存され、GitHub や Amazon API Gateway などの外部システムと同期できます。また、API Hub for Design 上でチームとコラボレーションしたり、API の進化に合わせて複数のバージョンを管理することも可能です。

この記事では、OpenAPI (REST) の例を説明しますが、AsyncAPI でもプロセスは同じです。

My API 画面

API Hub for Design にログインすると、MY API ページにアクセス可能なすべての API のリストが表示されます。このリストには、あなたが作成した API と、コラボレーションのため招待された API の両方が含まれます。

API Hub for Design で既存の API を検索するには、左側のサイドバーでをクリックしてアクセスできる検索ページを使用します。これにより、他の API Hub for Design ユーザーが開発した素晴らしいパブリック API を見つけることができます。検索構文については、「API Hub for Design の検索」を参照してください。

特定の API を表示するには、リストでその API をクリックします。

API Hub for Design の API ページでは、OpenAPI 定義の YAML コードと、それをベースに生成されたリファレンス形式の API ドキュメントが分割表示されます。フォームエディターでは API を表示でき、API ドキュメントではブラウザーで直接 API 呼び出しをテストできます。

左側のナビゲーションパネルには、API で定義された操作とモデルのリストが表示され、YAML コード内の対応する場所にジャンプできます。パネルのサイズを変更するには、パネル間のスプリッターをドラッグします。

次のステップは、API のデザイナーとコンシューマーでは異なります。適切なほうにお進みください。

API デザイナーの場合: API の作成
API コンシューマーの場合: リソースファイルの確認とコメントの追加

API Hub for Design を使用したサンプル API の作成

API デザイナーにとって、API Hub for Design を理解する最良の方法はサンプル 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] スライダー: ON にすると、ベースパスで API モックが作成されます。この例では OFF にします。

[Create API] をクリックします。API Hub for Design のフォームエディターが開き、入力した 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: {} 行を置換します。次のようになります。

仕様を編集すると、API Hub for Design は自動的に右側のプレビューを更新します。

ステップ 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/15) ではなく、URL パスの一部 (GET /users?id=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 が API Hub for Design に公開されました。ブラウザーのアドレスバーからアドレスをコピーして、他の人と共有できます。これはパブリック API であるため、リンクを持っている人は誰でも閲覧でき、API Hub for Design の検索結果にも表示されます。ご利用の API Hub プランで許可されている場合は、API をプライベートにすることができます。

公開された API は読み取り専用になり、API が再度非公開になった場合のみ編集できることに注意してください。description テキストを編集したり、タイプミスを修正する必要がある場合は、API を一時的に非公開にしても問題ありません。ただし、新しい操作やパラメーターなどの重大な変更の場合は、代わりに API Hub for Design エディターの [Add Version] コマンドを使用して新しいバージョンを開始する必要があります。API Hub for Design では API 仕様の複数のバージョンを維持できるため、公開済みのバージョン (「運用」バージョン) をそのまま維持しながら、次の API バージョンに取り組むことができます。

API Hub for Design エディターのその他の機能

API Hub for Design エディターは単なるエディターではなく、API 仕様を管理し、ワークフローに統合するためのツールを提供します。次の機能を利用できます。

[Settings] メニューでは、API の名前変更、フォーク、別のオーナーへの譲渡を行うことができます。
[Export] メニューでは、実装に必要な API のサーバーコードとクライアントコードを生成できます。また、OpenAPI 定義を YAML または JSON 形式でダウンロードすることもできます。