第2章 API Designer を使用した API 定義の設計および開発

手順

1. Fuse Online を使用している場合は、ステップ 2 に進みます。

   Fuse on OpenShift を使用している場合:

   1. OpenShift Web コンソールにログインし、API Designer が含まれるプロジェクトを開きます。

   2. アプリケーションの一覧で API Designer の URL をクリックします (例: https://apidesigner-myproject.192.168.64.43.nip.io)。

      API Designer の新しいブラウザーウィンドウまたはタブが開きます。

      注記

      API Designer は軽量バージョンの Apicurio Studio オープンソースプロジェクトであるため、「Apicurio」が API Designer インターフェースに表示されます。

2. New API をクリックします。新規の API ページが開きます。

3. API 名を変更するには、以下を実行します。

   1. 名前にカーソルを合わせ、表示される編集アイコン ( ) をクリックします。
   2. 名前を編集します。たとえば、Task API を入力します。
   3. 名前の変更を確認します。

4. オプションとして、以下を実行します。

   • 連絡先情報 (名前、メールアドレス、URL）を追加します。
   • ライセンスを選択します。
   • タグを定義します。
   • セキュリティースキームを定義します。
   • セキュリティー要件を指定します。

5. API のそれぞれのエンドポイントへの相対パスを定義します。フィールド名はスラッシュ (/) で開始する必要があります。

   Task Management API のサンプルでは、2 つのパスを作成します。

   • 複数のタスクのパス: /todo

   • ID 別の特定タスクのパス: /todo/{id}

     

6. 任意のパスパラメーターのタイプを指定します。

   id パラメーターのサンプルは、以下のようになります。

   1. Paths リストで、/todo/{id} をクリックします。

      id パラメーターが PATH PARAMETERS セクションに表示されます。

   2. Create をクリックします。
   3. description (説明) には、The ID of the task to find. と入力します。

   4. type (タイプ) には、integer を 32-Bit integer として選択します。

      

7. Data Types セクションで、API の再利用可能なタイプを定義します。

   1. Add a data type をクリックします。
   2. Add Data Type ダイアログで名前を入力します。Task Management API のサンプルでは、Todo と入力します。

   3. 任意で、API Designer がデータタイプのスキーマの作成に使用するサンプルを指定できます。生成されるスキーマを編集できます。

      Task Management API のサンプルでは、以下の JSON 例で開始します。

      {
          "id": 1,
          "task": "my task",
          "completed": false
      }

   4. オプションで、該当するデータタイプを指定して REST リソースの作成を選択できます。

   5. Save をクリックします。サンプルを指定している場合、API Designer はそのサンプルからスキーマを生成します。

      
8. オプションで、スキーマのプロパティーを編集し、新しいプロパティーを追加できます。

9. Task Management API のサンプルの場合、タイプ string の task という名前の 1 つのプロパティーを使用して、 Task という名前の別のデータタイプを作成します。

   

10. それぞれのパスについて、操作 (GET、PUT、POST、DELETE、 OPTIONS、HEAD、または PATCH) を定義します。

    Task Management API のサンプルの場合、以下の表で説明されているように操作を定義します。

    表2.1 Task Management API 操作

    パス	操作	説明	要求	応答
    /todo	POST	新しいタスクを作成します。	要求本体のタイプ: Task	ステータスコード: 201 説明: Task created レスポンスボディー: Todo タイプ
    /todo	GET	すべてのタスクを取得します。	該当なし	ステータスコード: 200 説明: Task deleted ステータスコード: 400 説明: Task not deleted
    /todo/{id}	GET	ID 別にタスクを取得します。	該当なし	ステータスコード: 200 説明: Task found for ID レスポンスボディー: Todo タイプ
    /todo/{id}	UPDATE	ID 別にタスクを更新します。	要求本体のタイプ: Task	ステータスコード: 200 説明: Completed ステータスコード: 400 説明: Task not updated
    /todo/{id}	DELETE	ID 別にタスクを削除します。	該当なし	ステータスコード: 200 説明: Task deleted ステータスコード: 400 説明: Task not deleted

11. 「API Designer での問題解決」に説明されているように問題を解決します。

12. Fuse on OpenShift のみの場合には、Save As をクリックして API 仕様を保存し、JSON または YAML 形式を選択します。

    JSON または YAML ファイルがローカルダウンロードフォルダーにダウンロードされます。デフォルトのファイル名は、適切なファイル拡張子を含む openapi-spec です。

手順

1. 感嘆符 (!) アイコンで示唆される問題を検索します。以下に例を示します。

   

2. 感嘆符アイコンをクリックして、問題の説明を表示します。以下に例を示します。

   

3. 問題の説明で提供される情報を基に、問題のある場所に移動して、修正します。

   たとえば、「Operation must have at least one response」(オペレーションには 1 つ以上の応答が必要) の問題を修正するには、GET オペレーションをクリックして開き、Add a response をクリックします。

   

   応答の説明の入力後、問題は解決され、感嘆符アイコンは表示されなくなります。

   

4. すべての問題の概要については、以下のようになります。

   1. 右上にある Issues リンクをクリックします。

      

   2. 特定の問題の Go to a problem をクリックし、その問題を解決するために問題のある場所に移動します。