Écrire et annoter le code

Cette page décrit comment structurer et annoter votre code Cloud Endpoints Frameworks. Pour obtenir la liste complète de toutes les annotations compatibles, consultez la page Annotations.

Avant de commencer

  1. Configurez votre environnement de développement.

  2. Clonez l'exemple de squelette Endpoints Frameworks :

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

  3. Cet exemple de squelette Endpoints Frameworks est disponible sous :

     cd appengine-java8/endpoints-v2-skeleton/

Dans ce document qui vous explique le fonctionnement des annotations, nous utilisons l'exemple endpoints-v2-backend pour afficher les annotations et tout autre code que vous devez ajouter à l'exemple endpoints-v2-skeleton afin qu'il soit généré. Au final, l'exemple endpoints-v2-skeleton modifié se comporte de la même manière que l'exemple endpoints-v2-backend, qui est utilisé sur la page Premiers pas avec Endpoints Frameworks sur App Engine.

Créer et annoter le code

Pour annoter votre code, procédez comme suit :

  1. Remplacez les répertoires actuels par le répertoire source Java du projet, par exemple : src/main/java/com/example/skeleton.
  2. Créez un fichier de classe JavaBean nommé Message.java contenant le code suivant : 
    public class Message {

  private String message;

  public String getMessage() {
    return this.message;
  }

  public void setMessage(String message) {
    this.message = message;
  }
}
  3. Modifiez le fichier MyApi.java contenu dans l'exemple de squelette. Modifiez l'annotation de définition @Api comme suit : 
    @Api(
    name = "echo",
    version = "v1",
    namespace =
    @ApiNamespace(
        ownerDomain = "echo.example.com",
        ownerName = "echo.example.com",
        packagePath = ""
    ),
    // ...
)

    L'attribut version = "v1" spécifie la version de l'exemple d'API. La valeur que vous saisissez est incorporée dans le chemin spécifié dans l'URL de votre API. Pour en savoir plus sur les versions, consultez la page Gérer les versions d'une API.

  4. Ajoutez la méthode echo suivante comme premier point de terminaison de l'API ainsi que la méthode d'assistance doEcho au fichier 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. Copiez toutes les importations à partir de Echo.java, puis collez-les dans MyApi.java.

  6. Maven

    Créez le projet :

    mvn clean package

    Gradle

    Créez le projet :

    gradle clean build

Principes de base des annotations

Trois types d'annotations sont couramment utilisées dans les API backend :

  • L'annotation @Api contient les détails de configuration de l'API backend.
  • L'annotation @ApiMethod marque une méthode de classe associée à l'API backend. Les méthodes qui ne sont pas marquées avec @ApiMethod ne sont pas incluses lorsque vous générez des bibliothèques clientes et des documents de découverte. L'annotation @ApiMethod peut également être utilisée afin de remplacer la configuration de l'API pour une méthode spécifique.
  • L'annotation @Named doit être ajoutée à tous les paramètres transmis aux méthodes côté serveur, sauf si le paramètre est un type d'entité.

Pour obtenir la liste complète de toutes les annotations Endpoints Frameworks, consultez la page Annotations et syntaxe.

Étapes suivantes