Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# 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'[PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API comme exemple. Pour créer une API à l'aide de la console API Gateway, suivez les instructions de [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
**Topics**
+ [Documentation de l'entité `API`](#api-gateway-document-api-add-document-part-for-api-entity-with-console)
+ [Documentation d'une entité `RESOURCE`](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [Documentation d'une entité `METHOD`](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [Documentation d'une entité `QUERY_PARAMETER`](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [Documentation d'une entité `PATH_PARAMETER`](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [Documentation d'une entité `REQUEST_HEADER`](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [Documentation d'une entité `REQUEST_BODY`](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [Documentation d'une entité `RESPONSE`](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [Documentation d'une entité `RESPONSE_HEADER`](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [Documentation d'une entité `RESPONSE_BODY`](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [Documentation d'une entité `MODEL`](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [Documentation d'une entité `AUTHORIZER`](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)
## 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**.
1. 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": "john.doe@api.com"
}
}
}
```
**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.
1. 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**.
1. Choisissez le menu **Actions API**, puis **Mettre à jour la documentation de l’API**.
![\[Modification de la documentation de l’entité API sur la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)
Pour modifier une partie de la documentation existante, procédez comme suit :
1. Dans le volet **Documentation**, choisissez l'onglet **Ressources et méthodes**.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Ressource**.
1. Pour **Chemin**, entrez un chemin.
1. Entrez une description dans l'éditeur de texte, par exemple :
```
{
"description": "The PetStore's root resource."
}
```
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour une ressource non répertoriée.
1. 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**.
1. Choisissez la ressource, puis **Mettre à jour la documentation**.
![\[Modification de la documentation de l’entité ressource sur la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)
Pour modifier une partie de la documentation existante, procédez comme suit :
1. Dans le volet **Documentation**, choisissez l'onglet **Ressources et méthodes**.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Méthode**.
1. Pour **Chemin**, entrez un chemin.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Entrez une description dans l'éditeur de texte, par exemple :
```
{
"tags" : [ "pets" ],
"summary" : "List all pets"
}
```
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour une méthode non répertoriée.
1. 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**.
1. Choisissez la méthode, puis **Mettre à jour la documentation**.
![\[Modification de la documentation de l’entité méthode sur la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)
Pour modifier une partie de la documentation existante, procédez comme suit :
1. Dans le volet **Documentation**, choisissez l'onglet **Ressources et méthodes**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Paramètre de requête**.
1. Pour **Chemin**, entrez un chemin.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Nom**, entrez un nom.
1. Entrez une description dans l'éditeur de texte.
1. 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é.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Paramètre de chemin**.
1. Pour **Chemin**, entrez un chemin.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Nom**, entrez un nom.
1. Entrez une description dans l'éditeur de texte.
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour un paramètre de chemin non répertorié.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **En-tête de demande**.
1. Pour **Chemin**, entrez un chemin pour l’en-tête de demande.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Nom**, entrez un nom.
1. Entrez une description dans l'éditeur de texte.
1. 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é.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Corps de la demande**.
1. Pour **Chemin**, entrez un chemin pour le corps de la demande.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Entrez une description dans l'éditeur de texte.
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour un corps de la demande non répertorié.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Réponse (code de statut)**.
1. Pour **Chemin**, entrez un chemin pour la réponse.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Code de statut**, entrez un code de statut HTTP.
1. Entrez une description dans l'éditeur de texte.
1. 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é.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **En-tête de réponse**.
1. Pour **Chemin**, entrez un chemin pour l’en-tête de réponse.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Code de statut**, entrez un code de statut HTTP.
1. Entrez une description dans l'éditeur de texte.
1. 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é.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Corps de la réponse**.
1. Pour **Chemin**, entrez un chemin pour le corps de la réponse.
1. Pour **Méthode**, sélectionnez un verbe HTTP.
1. Pour **Code de statut**, entrez un code de statut HTTP.
1. Entrez une description dans l'éditeur de texte.
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour un corps de réponse non répertorié.
1. 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**.
1. 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.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Modèle**.
1. Pour **Nom**, entrez un nom pour le modèle.
1. Entrez une description dans l'éditeur de texte.
1. Choisissez **Créer une partie de la documentation**. Vous pouvez créer de la documentation pour des modèles non répertoriés.
1. 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**.
1. Choisissez le modèle, puis **Mettre à jour la documentation**.
![\[Modification de la documentation de l’entité modèle sur la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)
Pour modifier une partie de la documentation existante, procédez comme suit :
1. Dans le volet **Documentation**, choisissez l’onglet **Modèles**.
1. 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**.
1. Pour **Type de documentation**, sélectionnez **Mécanisme d’autorisation**.
1. Pour **Nom**, entrez le nom de votre mécanisme d’autorisation.
1. Entrez une description dans l'éditeur de texte. Spécifiez une valeur pour le champ `location` valide pour le mécanisme d’autorisation.
1. 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.
1. 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**.
1. Utilisez la barre de recherche ou sélectionnez le mécanisme d’autorisation, puis choisissez **Modifier**.