API の設計

手順

1. Web ブラウザーで OpenShift コンソールを開き、認証情報 (例: ユーザー名 developer およびパスワード developer) を使用してログインします。
2. API Designer Operator が含まれるプロジェクトを選択します。

3. Topology を選択し、fuse-apicurito というラベルが付けられたアイコンが表示されることを確認します。

   apicurito-service-ui および apicurito-service-generator のアイコンがある場合は、OpenShift 管理者は API Designer をサービスとしてプロジェクトに追加済みなので、残りのステップを省略できます。

   apicurito-service-ui および apicurito-service-generator のアイコンがない場合は、次の手順に進みます。

4. 左側のナビゲーションペインで Add+ をクリックします。
5. Developer Catalog セクションで、Operator Backed をクリックします。
6. 検索フィールドに Apicurito と入力し、カタログソースをフィルターします。
7. Apicurito provided by Red Hat カードをクリックします。

8. Create をクリックします。

   API Designer インスタンスの最小限の開始テンプレートがあるデフォルトのフォームが開かれます。デフォルト値を使用するか、任意でデフォルト値を編集します。

9. Create をクリックし、新しい API Designer インスタンスの Pod、サービス、およびその他のコンポーネントの起動をトリガーします。
10. API Designer サービスがプロジェクトに追加されたことを確認するには、Topology を選択し、apicurito-service-ui および apicurito-service-generator のアイコンが表示されることを確認します。
11. API デザイナーを開くには、apicurito-service-ui アイコンの URL リンクをクリックします。

1. コマンドウィンドウで、OpenShift サーバーにログインします。

   oc login -u developer -p developer

2. 新規プロジェクト namespace を作成します。たとえば、以下のコマンドは myproject という名前の新規プロジェクトを作成します。

   oc new-project myproject

3. 次のコマンド (myprojectはプロジェクトの名前) を実行して、APIDesigner テンプレートに基づいて新しいアプリケーションを作成します。

   oc new-app -n myproject -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-sb2-7_10_0-00015-redhat-00001/fuse-apicurito.yml -p ROUTE_HOSTNAME=myhost

   注: オプションで、oc new-app コマンドに追加の -p オプションを追加することにより、他のテンプレートパラメーターを指定できます。たとえば、Fuse on OpenShift イメージおよびテンプレートをデフォルトの openshift namespace 以外の namespace にインストールしている場合、IMAGE_STREAM_NAMESPACE を設定して、Fuse イメージストリームがインストールされている namespace を指定できます。

   oc new-app -n myproject -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-sb2-7_10_0-00015-redhat-00001/fuse-apicurito.yml -p ROUTE_HOSTNAME=myhost -p IMAGE_STREAM_NAMESPACE=othernamespace

4. 以下のコマンドを実行して、API Designer デプロイメントのステータスおよび URL を取得します。

   oc status

   API Designer がデプロイされていない場合は、次のコマンドを実行して、正しいバージョンの apicurito-ui および fuse-apicurito-generator イメージがインストールされていることを確認します。

   oc get is -n openshift | grep "apicurito"

5. ブラウザーから API Designer にアクセスするには、提供される URL (例: https://apicurito.192.168.64.12.nip.io) を使用します。

手順

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

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

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

   2. OpenShift 4.x の場合は、Topology を選択し、apicurito-service-ui アイコンの URL リンクをクリックします。

      OpenShift 3.11 の場合は、アプリケーションの一覧で 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 ページが開きます。

   デフォルトでは、API Designer は OpenAPI 3 仕様を使用します。OpenAPI 2 仕様を使用する場合は、New API ボタンの横にある矢印をクリックし、OpenAPI 2 を選択します。

   注記

   OpenAPI 2 仕様に基づいて API を開く場合、API Designer の Convert to OpenAPI 3 オプションを使用して、API が OpenAPI 3 仕様に準拠するよう変換することができます。

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

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

4. 任意で以下を行います。

   • バージョン番号と説明を提供します。
   • 連絡先情報 (名前、メールアドレス、および URL) を追加します。
   • ライセンスを選択します。
   • タグを定義します。
   • サーバーを 1 つ以上定義します。
   • セキュリティースキームを設定します。
   • セキュリティー要件を指定します。

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 のサンプルの場合、以下の表で説明されているように操作を定義します。

    表3.1 Task Management API 操作

    パス	操作	説明	リクエストボディー	応答
    /todo	POST	新しいタスクを作成します。	メディアタイプ: application/json データタイプ: Task	ステータスコード: 201 説明: Task created 応答ボディー: メディアタイプ: application/json データタイプ: Todo
    /todo	GET	すべてのタスクを取得します。	該当なし	ステータスコード: 200 説明: タスクのリスト
    /todo/{id}	GET	ID 別にタスクを取得します。	該当なし	ステータスコード: 200 説明: Task found for ID 応答ボディー: メディアタイプ: application/json データタイプ: Task ステータスコード: 404 説明: No task with provided identifier found.
    /todo/{id}	PUT	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 をクリックし、その問題を解決するために問題のある場所に移動します。

      

手順

1. OpenShift Web コンソールで、API Designer を含むプロジェクトを開きます。

2. API Designer コンソールを開きます。プロジェクトのアプリケーション一覧で、apidesigner の下にある URL をクリックします。例: https://apidesigner-myproject.192.168.64.38.nip.io

   API Designer コンソールは、別の Web ブラウザータブまたはウインドウで開きます。

3. Open API をクリックします。

   ファイルマネージャーウィンドウが開きます。

4. ファイルマネージャーウィンドウで、以下を実行します。

   1. 既存の OpenAPI 定義ファイル (例: openapi.json) が含まれるフォルダーに移動します。

   2. OpenAPI 定義ファイルを選択し、Open をクリックします。

      OpenAPI 定義が API Designer コンソールで開きます。

1. Generate をクリックします。
2. ドロップダウンリストから Fuse Camel Project を選択します。

手順

1. API Designer によって生成された camel-project.zip ファイルを一時フォルダーに解凍します。
2. Red Hat Developer Studio を開きます。
3. Developer Studio で File → Import を選択します。
4. Import ダイアログで、Maven → Existing Maven Projects を選択します。
5. エディタービューでプロジェクトの camel-context.xml ファイルを開きます。

6. REST タブをクリックして Rest DSL コンポーネントを編集します。

   REST サービスの定義についての詳細は、Apache Camel Development Guide の Defining REST services セクションを参照してください。

   Swagger サポートで JAX-RS エンドポイントを拡張する方法については、Apache CXF Development Guide を参照してください。

   Fuse Tooling REST エディターの使用方法は、Tooling User Guide の Viewing and editing Rest DSL components セクションを参照してください。

7. Design タブで Camel ルートを編集します。

   Camel ルートの編集に関する詳細は、Tooling User Guide の Editing a routing context in the route editor セクションを参照してください。

1. OpenShift クラスターにログインします。

   $ oc login -u developer -p developer

2. プロジェクトの新規 OpenShift プロジェクトを作成します。たとえば、以下のコマンドは test-deploy という名前の新規プロジェクトを作成します。

   $ oc new-project test-deploy

3. ディレクトリーを Fuse Camel プロジェクトが含まれるフォルダーに変更します (例: myworkspace/camel-project)。

   $ cd myworkspace/camel-project

4. プロジェクトを OpenShift クラスターにビルドし、デプロイします。

   $ mvn clean fabric8:deploy -Popenshift

5. ブラウザーで OpenShift コンソールを開き、プロジェクト (例: test-deploy) に移動します。camel-project アプリケーションの Pod が起動していることを確認できるまで待機します。
6. プロジェクトの Overview ページで、camel-project アプリケーションの URL を特定します。URL は http://camel-project-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io という形式を使用します。
7. URL をクリックしてサービスにアクセスします。

1. 以下の例のように、Fuse プロジェクトの pom.xml ファイルを編集し、openshift-maven-plugin 依存関係を組み込みます。

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>openshift-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

   OpenShift Maven Plugin は、特定のプロジェクトレベルの条件が満たされる場合は Service Discovery Enricher を実行します (例: プロジェクトは Camel Rest DSL プロジェクトである必要があります)。API サービスアノテーション値のカスタマイズ の説明にあるように、 Enricher の動作をカスタマイズする必要がない場合は、Service Discovery Enricher を pom.xml ファイルで依存関係として指定する必要はありません。

2. Fuse Rest DSL プロジェクトの camel-context.xml ファイルで、以下の属性を restConfiguration 要素に指定します。

   • scheme: サービスがホストされる URL のスキームの部分です。http または https を指定できます。
   • contextPath: API サービスがホストされる URL のパスの部分です。

   • apiContextPath: API サービスの記述ドキュメントがホストされる場所へのパスです。ドキュメントがセルフホストされている場合は相対パスを指定でき、ドキュメントが外部でホストされる場合は完全な URL を指定できます。

     サンプル camel-context.xml ファイルからの以下の抜粋には、アノテーションの属性値が restConfiguration 要素に表示されています。

     <?xml version="1.0" encoding="UTF-8"?>
     <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
            http://camel.apache.org/schema/spring       http://camel.apache.org/schema/spring/camel-spring.xsd">
     
         <camelContext xmlns="http://camel.apache.org/schema/spring">
             <restConfiguration component="servlet" scheme="https"
                   contextPath="myapi" apiContextPath="myapi/openapi.json"/>
     ...

1. 任意のエディターで Fuse プロジェクトの pom.xml ファイルを開きます。

2. 以下の例のように、openshift-maven-plugin の依存関係を見つけます。

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>openshift-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

3. 以下の例のように、Fabric8 Service Discovery Enricher を openshift-maven プラグインに依存関係として追加します。

   <plugin>
     <groupId>org.jboss.redhat-fuse</groupId>
     <artifactId>openshift-maven-plugin</artifactId>
     <version>${fuse.version}</version>
     <executions>
       <execution>
         <goals>
           <goal>resource</goal>
           <goal>build</goal>
         </goals>
       </execution>
     </executions>
     <dependencies>
       <dependency>
         <groupId>io.acme</groupId>
         <artifactId>myenricher</artifactId>
         <version>1.0</version>
         <configuration>
           <enricher>
             <config>
               <f8-service-discovery>
                 <scheme>https</scheme>
                 <path>/api</path>
                 <descriptionPath>/api/openapi.json</descriptionPath>
               </f8-service-discovery>
             </config>
           </enricher>
         </configuration>
         </dependency>
     </dependencies>
   </plugin>

4. 変更を保存します。