Como escrever e fazer anotações no código

Esta página descreve como estruturar e anotar seu código do Cloud Endpoints Frameworks. Para ver uma lista completa de todas as anotações compatíveis, consulte Anotações.

Antes de começar

  1. Configure o ambiente de desenvolvimento.
  2. Clone o exemplo de estrutura do Endpoints Frameworks:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    
  3. O exemplo de estrutura do Endpoints Frameworks está localizado em:

     cd appengine-java8/endpoints-v2-skeleton/
    

Para ajudar a explicar como as anotações funcionam, neste documento, usamos a amostra endpoints-v2-backend para expor as anotações e outro código que você precisa incluir na amostra endpoints-v2-skeleton para o desenvolvimento. No final, a amostra modificada endpoints-v2-skeleton se comporta igual à amostra endpoints-v2-backend que é usada nos Primeiros passos com o Endpoints Frameworks no App Engine.

Como criar e anotar código

Para anotar seu código:

  1. Altere os diretórios para o diretório de origem Java do projeto, por exemplo: src/main/java/com/example/skeleton.
  2. Crie um arquivo de classe JavaBean chamado Message.java que contenha o seguinte código:
    public class Message {
    
      private String message;
    
      public String getMessage() {
        return this.message;
      }
    
      public void setMessage(String message) {
        this.message = message;
      }
    }
  3. Edite o arquivo MyApi.java no exemplo de estrutura. Altere a anotação de definição @Api com o seguinte:
    @Api(
        name = "echo",
        version = "v1",
        namespace =
        @ApiNamespace(
            ownerDomain = "echo.example.com",
            ownerName = "echo.example.com",
            packagePath = ""
        ),
        // ...
    )

    O atributo version = "v1" especifica a versão da API de amostra. O valor inserido se torna parte do caminho no URL para a API. Para mais informações sobre as versões, consulte Como gerenciar o controle de versões da API.

  4. Adicione o seguinte método echo como seu primeiro endpoint de API e o método auxiliar doEcho ao seu MyApi.java.
    @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. Copie todas as importações de Echo.java e cole-as no MyApi.java.
  6. Maven

    Crie o projeto:

    mvn clean package

    Gradle

    Crie o projeto:

    gradle clean build

Noções básicas de anotações

Há três anotações comumente usadas em APIs de back-end:

  • @Api contém os detalhes de configuração da API de back-end.
  • @ApiMethod marca um método de classe que faz parte da API de back-end. Os métodos não marcados com @ApiMethod não são incluídos quando você gera bibliotecas de clientes e documentos de descoberta. A anotação @ApiMethod também pode ser usada para substituir a configuração da API para um método específico.
  • @Named deve ser adicionado a todos os parâmetros transmitidos aos métodos do lado do servidor, a menos que o parâmetro seja um tipo de entidade.

Para ver uma lista completa de todas as anotações do Endpoints Frameworks, consulte Anotações e sintaxe.

A seguir