コードの書き込みとアノテーション

このページでは、Cloud Endpoints Frameworks のコードを構造化し、アノテーションを付ける方法について説明します。サポートされているすべてのアノテーションのリストについては、アノテーションをご覧ください。

始める前に

1. 開発環境をセットアップします。

2. スケルトン Endpoints Frameworks のサンプルのクローンを作成します。

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
   

3. スケルトン Endpoints Frameworks のサンプルは次の場所にあります。

    cd appengine-java8/endpoints-v2-skeleton/
   

アノテーションの機能の説明に役立つように、ここでは endpoints-v2-backend サンプルを使用し、このサンプルをビルドする際に endpoints-v2-skeleton サンプルに追加する必要があるアノテーションやその他のコードを示します。最終的に、変更された endpoints-v2-skeleton サンプルは、App Engine での Endpoints Frameworks スタートガイドで使用されている endpoints-v2-backend サンプルと同じように動作します。

コードの作成とアノテーションの付加

コードにアノテーションを付けるには:

1. ディレクトリをプロジェクトの Java ソース ディレクトリ（src/main/java/com/example/skeleton など）に変更します。
2. 次のコードが含まれている Message.java という名前の JavaBeanクラスファイルを作成します。
   public class Message {
   
     private String message;
   
     public String getMessage() {
       return this.message;
     }
   
     public void setMessage(String message) {
       this.message = message;
     }
   }

3. スケルトンのサンプルに含まれている MyApi.java ファイルを編集します。@Api 定義のアノテーションを次のように変更します。
   @Api(
       name = "echo",
       version = "v1",
       namespace =
       @ApiNamespace(
           ownerDomain = "echo.example.com",
           ownerName = "echo.example.com",
           packagePath = ""
       ),
       // ...
   )

   version = "v1" 属性はサンプル API のバージョンを指定します。入力する値は、API への URL 内のパスの一部になります。バージョンの詳細については、API のバージョニングの処理をご覧ください。

4. MyApi.java に次の echo メソッドを最初の API エンドポイントとして追加し、さらに doEcho ヘルパー メソッドを追加します。
   @ApiMethod(name = "echo")
   public Message echo(Message message, @Named("n") @Nullable Integer n) {
     return doEcho(message, n);
   }

   private Message doEcho(Message request, Integer n) {
     Message response = new Message();
     if (n != null && n >= 0) {
       StringBuilder sb = new StringBuilder();
       for (int i = 0; i < n; i++) {
         if (i > 0) {
           sb.append(' ');
         }
         sb.append(request.getMessage());
       }
       response.setMessage(sb.toString());
     }
     return response;
   }

5. Echo.java からのインポートをすべてコピーし、MyApi.java に貼り付けます。

6. Maven

   プロジェクトをビルドします。

   mvn clean package

   Gradle

   プロジェクトをビルドします。

   gradle clean build

アノテーションの基礎

バックエンドの API でよく使用される次の 3 つのアノテーションがあります。

• @Api: バックエンド API の構成の詳細を含んでいます。
• @ApiMethod: バックエンド API に含まれるクラスのメソッドにマークを付けます。クライアントがライブラリとディスカバリ ドキュメントを生成するとき @ApiMethod のマークがないメソッドは含まれません。また、特定のメソッド用の API 構成をオーバーライドするために @ApiMethod アノテーションを使用することもできます。
• @Named: サーバー側のメソッドに渡されるすべてのパラメータにこれを追加する必要があります（ただしパラメータがエンティティ タイプである場合を除く）。

Endpoints Frameworks のすべてのアノテーションの完全なリストについては、アノテーションと構文をご覧ください。

次のステップ

• API 管理の追加について学びます。
• サポートされているパラメータと戻り値の型について学びます。
• 例外とステータス コードについて学びます。