Documentation d'une API avec la console API Gateway

Dans cette section, nous décrivons la création et la gestion des parties de la documentation d'une API à l'aide de la console API Gateway.

Pour créer et de modifier la documentation d'une API, vous devez avoir déjà créé l'API. Dans cette section, nous utilisons l'API PetStore à titre d'exemple. Pour créer une API à l'aide de la console API Gateway, suivez les instructions de Tutoriel : Création d'une API REST par l'importation d'un exemple.

Documentation de l'entité API

Pour ajouter une nouvelle partie de la documentation pour l'entité API, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis choisissez Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez API.

   Si une partie de la documentation n'a pas été créée pour l'API, vous obtenez l'éditeur de mappage properties de la partie de la documentation. Entrez la carte properties suivante dans l'éditeur de texte.

   {
     "info": {
       "description": "Your first API Gateway API.",
       "contact": {
           "name": "John Doe",
           "email": "[e-mail]"
       }
     }
   }

   Note

   Vous n'avez pas besoin d'encoder le mappage properties en une chaîne JSON. La console API Gateway convertit automatiquement l'objet JSON en chaîne.

3. Choisissez Créer une partie de la documentation.

Pour ajouter une nouvelle partie de la documentation pour l'entité API dans le volet Ressources, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Ressources.

2. Choisissez le menu Actions API, puis Mettre à jour la documentation de l'API.

   

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Sélectionnez le nom de votre API, puis sur la carte de l'API, choisissez Modifier.

Documentation d'une entité RESOURCE

Pour ajouter une nouvelle partie de la documentation pour une entité RESOURCE, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Ressource.

3. Pour Chemin, entrez un chemin.

4. Entrez une description dans l'éditeur de texte, par exemple :

   {
       "description": "The PetStore's root resource."
   }

5. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour une ressource non répertoriée.

6. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour ajouter une nouvelle partie de la documentation pour une entité RESOURCE dans le volet Ressources, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Ressources.

2. Choisissez la ressource, puis Mettre à jour la documentation.

   

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Sélectionnez la ressource contenant votre partie de la documentation, puis choisissez Modifier.

Documentation d'une entité METHOD

Pour ajouter une nouvelle partie de la documentation pour une entité METHOD, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Méthode.

3. Pour Chemin, entrez un chemin.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Entrez une description dans l'éditeur de texte, par exemple :

   {
     "tags" : [ "pets" ],
     "summary" : "List all pets"
   }

6. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour une méthode non répertoriée.

7. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour ajouter une nouvelle partie de la documentation pour une entité METHOD dans le volet Ressources, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Ressources.

2. Choisissez la méthode, puis Mettre à jour la documentation.

   

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner la méthode ou la ressource contenant la méthode, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité QUERY_PARAMETER

Pour ajouter une nouvelle partie de la documentation pour une entité QUERY_PARAMETER, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Paramètre de requête.

3. Pour Chemin, entrez un chemin.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Nom, entrez un nom.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un paramètre de requête non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner le paramètre de requête ou la ressource contenant le paramètre de requête, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité PATH_PARAMETER

Pour ajouter une nouvelle partie de la documentation pour une entité PATH_PARAMETER, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Paramètre de chemin.

3. Pour Chemin, entrez un chemin.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Nom, entrez un nom.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un paramètre de chemin non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner le paramètre de chemin ou la ressource contenant le paramètre de chemin, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité REQUEST_HEADER

Pour ajouter une nouvelle partie de la documentation pour une entité REQUEST_HEADER, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez En-tête de demande.

3. Pour Chemin, entrez un chemin pour l'en-tête de demande.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Nom, entrez un nom.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un en-tête de demande non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner l'en-tête de demande ou la ressource contenant l'en-tête de demande, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité REQUEST_BODY

Pour ajouter une nouvelle partie de la documentation pour une entité REQUEST_BODY, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Corps de la demande.

3. Pour Chemin, entrez un chemin pour le corps de la demande.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Entrez une description dans l'éditeur de texte.

6. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un corps de la demande non répertorié.

7. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner le corps de la demande ou la ressource contenant le corps de la demande, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité RESPONSE

Pour ajouter une nouvelle partie de la documentation pour une entité RESPONSE, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Réponse (code de statut).

3. Pour Chemin, entrez un chemin pour la réponse.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Code de statut, entrez un code de statut HTTP.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un code de statut de réponse non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner le code de statut de réponse ou la ressource contenant le code de statut de réponse, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité RESPONSE_HEADER

Pour ajouter une nouvelle partie de la documentation pour une entité RESPONSE_HEADER, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez En-tête de réponse.

3. Pour Chemin, entrez un chemin pour l'en-tête de réponse.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Code de statut, entrez un code de statut HTTP.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un en-tête de réponse non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner l'en-tête de réponse ou la ressource contenant l'en-tête de réponse, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité RESPONSE_BODY

Pour ajouter une nouvelle partie de la documentation pour une entité RESPONSE_BODY, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Corps de la réponse.

3. Pour Chemin, entrez un chemin pour le corps de la réponse.

4. Pour Méthode, sélectionnez un verbe HTTP.

5. Pour Code de statut, entrez un code de statut HTTP.

6. Entrez une description dans l'éditeur de texte.

7. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un corps de réponse non répertorié.

8. Si nécessaire, répétez ces étapes pour ajouter ou modifier une autre partie de la documentation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.

2. Vous pouvez sélectionner le corps de la réponse ou la ressource contenant le corps de la réponse, puis utiliser la barre de recherche pour rechercher et sélectionner la partie de votre documentation.

3. Choisissez Modifier.

Documentation d'une entité MODEL

La documentation d'une entité MODEL implique la création et la gestion d'instances DocumentPart pour le modèle et chacune des properties du modèle. Par exemple, le modèle Error qui est associé à chaque API par défaut a la définition de schéma suivante,

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "Error Schema",
  "type" : "object",
  "properties" : {
    "message" : { "type" : "string" }
  }
}

et exige deux instances DocumentationPart, une pour le Model et l'autre pour sa propriété message :

{
  "location": {
    "type": "MODEL",
    "name": "Error"
  },
  "properties": {
    "title": "Error Schema",
    "description": "A description of the Error model"
  }
}

et

{
  "location": {
    "type": "MODEL",
    "name": "Error.message"
  },
  "properties": {
    "description": "An error message."
  }
}

Lorsque l'API est exportée, les propriétés de DocumentationPart remplacent les valeurs dans le schéma d'origine.

Pour ajouter une nouvelle partie de la documentation pour une entité MODEL, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Modèle.

3. Pour Nom, entrez un nom pour le modèle.

4. Entrez une description dans l'éditeur de texte.

5. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour des modèles non répertoriés.

6. Si nécessaire, répétez ces étapes pour ajouter ou modifier une partie de la documentation à d'autres modèles.

Pour ajouter une nouvelle partie de la documentation pour une entité MODEL dans le volet Modèles, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Modèles.

2. Choisissez le modèle, puis Mettre à jour la documentation.

   

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Modèles.

2. Utilisez la barre de recherche ou sélectionnez le modèle, puis choisissez Modifier.

Documentation d'une entité AUTHORIZER

Pour ajouter une nouvelle partie de la documentation pour une entité AUTHORIZER, procédez comme suit :

1. Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.

2. Pour Type de documentation, sélectionnez Mécanisme d'autorisation.

3. Pour Nom, entrez le nom de votre mécanisme d'autorisation.

4. Entrez une description dans l'éditeur de texte. Spécifiez une valeur pour le champ location valide pour le mécanisme d'autorisation.

5. Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour des mécanismes d'autorisation non répertoriés.

6. Si nécessaire, répétez ces étapes pour ajouter ou modifier une partie de la documentation à d'autres mécanismes d'autorisation.

Pour modifier une partie de la documentation existante, procédez comme suit :

1. Dans le volet Documentation, choisissez l'onglet Mécanismes d'autorisation.

2. Utilisez la barre de recherche ou sélectionnez le mécanisme d'autorisation, puis choisissez Modifier.