Escribe y anota el código

En esta página, se describe cómo estructurar y anotar el código de Cloud Endpoints Frameworks. Para obtener una lista completa de todas las anotaciones compatibles, consulta Anotaciones.

Antes de comenzar

  1. Configura tu entorno de desarrollo.
  2. Clona el ejemplo de esqueleto de Endpoints Frameworks:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    
  3. El ejemplo de esqueleto de Endpoints Frameworks se ubica en:

     cd appengine-java8/endpoints-v2-skeleton/
    

Para ayudar a explicar cómo funcionan las anotaciones, este documento usa la muestra endpoints-v2-backend a fin de exponer las anotaciones y otros códigos que debes agregar a la muestra endpoints-v2-skeleton para poder crearla. Al final, la muestra modificada endpoints-v2-skeleton se debe comportar de la misma manera que la muestra endpoints-v2-backend, que se usa en el instructivo para comenzar a usar Endpoints Frameworks en App Engine.

Crea y anota un código

Para anotar tu código:

  1. Cambia los directorios al directorio fuente de Java del proyecto; por ejemplo: src/main/java/com/example/skeleton.
  2. Crea un archivo de clase JavaBean denominado Message.java que contiene el código siguiente:
    public class Message {
    
      private String message;
    
      public String getMessage() {
        return this.message;
      }
    
      public void setMessage(String message) {
        this.message = message;
      }
    }
  3. Edita el archivo MyApi.java que se encuentra en el ejemplo de esqueleto. Cambia la anotación de definición @Api por lo siguiente:
    @Api(
        name = "echo",
        version = "v1",
        namespace =
        @ApiNamespace(
            ownerDomain = "echo.example.com",
            ownerName = "echo.example.com",
            packagePath = ""
        ),
        // ...
    )

    El atributo version = "v1" especifica la versión de la API de muestra. El valor que ingreses se vuelve parte de la ruta en la URL de tu API. Para obtener más información sobre el control de versiones, consulta Administra el control de versiones de API.

  4. Agrega el método echo como tu primer extremo de API y el método de ayuda doEcho a tu 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. Copia todas las importaciones desde Echo.java y pégalas en tu MyApi.java.
  6. Maven

    Compila el proyecto:

    mvn clean package

    Gradle

    Compila el proyecto:

    gradle clean build

Conceptos básicos de las anotaciones

Son tres las anotaciones que se suelen usar en las API de backend:

  • @Api contiene los detalles de configuración de la API de backend.
  • @ApiMethod marca un método de clase que forma parte de la API de backend. Los métodos que no están marcados con @ApiMethod no se incluyen cuando se generan bibliotecas cliente y documentos de descubrimiento. La anotación @ApiMethod también se puede usar para anular la configuración de API de un método específico.
  • @Named se debe agregar a todos los parámetros pasados a los métodos del lado del servidor, a menos que el parámetro sea un tipo de entidad.

Para obtener una lista completa de todas las anotaciones de Endpoints Frameworks, consulta Anotaciones y sintaxis.

¿Qué sigue?