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.
Documenter et API utiliser la console API Gateway
Dans cette section, nous décrivons comment créer et gérer les parties de documentation d'une console API utilisant la API passerelle.
Une condition préalable à la création et à la modification de la documentation d'un API est que vous devez déjà avoir créé leAPI. Dans cette section, nous utilisons le PetStore
Rubriques
- Documentation de l'entité API
- Documentation d'une entité RESOURCE
- Documentation d'une entité METHOD
- Documentation d'une entité QUERY_PARAMETER
- Documentation d'une entité PATH_PARAMETER
- Documentation d'une entité REQUEST_HEADER
- Documentation d'une entité REQUEST_BODY
- Documentation d'une entité RESPONSE
- Documentation d'une entité RESPONSE_HEADER
- Documentation d'une entité RESPONSE_BODY
- Documentation d'une entité MODEL
- Documentation d'une entité AUTHORIZER
Documentation de l'entité API
Pour ajouter une nouvelle partie de la documentation pour l'entité API
, procédez comme suit :
Dans le volet de navigation principal, choisissez Documentation, puis choisissez Créer une partie de la documentation.
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 mappageproperties
de la partie de la documentation. Entrez la carteproperties
suivante dans l'éditeur de texte.{ "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } }
Note
Il n'est pas nécessaire de coder la
properties
carte JSON sous forme de chaîne. La console API Gateway stringifie l'JSONobjet pour vous.-
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 :
Dans le volet de navigation principal, choisissez Ressources.
Choisissez le menu APIActions, puis choisissez Mettre à jour API la documentation.
Pour modifier une partie de la documentation existante, procédez comme suit :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
Sélectionnez le nom de votreAPI, puis sur la API carte, choisissez Modifier.
Documentation d'une entité RESOURCE
Pour ajouter une nouvelle partie de la documentation pour une entité RESOURCE
, procédez comme suit :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Ressource.
Pour Chemin, entrez un chemin.
Entrez une description dans l'éditeur de texte, par exemple :
{ "description": "The PetStore's root resource." }
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour une ressource non répertoriée.
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 :
Dans le volet de navigation principal, choisissez Ressources.
Choisissez la ressource, puis Mettre à jour la documentation.
Pour modifier une partie de la documentation existante, procédez comme suit :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Méthode.
Pour Chemin, entrez un chemin.
Pour Méthode, sélectionnez un HTTP verbe.
Entrez une description dans l'éditeur de texte, par exemple :
{ "tags" : [ "pets" ], "summary" : "List all pets" }
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour une méthode non répertoriée.
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 :
Dans le volet de navigation principal, choisissez Ressources.
Choisissez la méthode, puis Mettre à jour la documentation.
Pour modifier une partie de la documentation existante, procédez comme suit :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Paramètre de requête.
Pour Chemin, entrez un chemin.
Pour Méthode, sélectionnez un HTTP verbe.
Pour Nom, entrez un nom.
Entrez une description dans l'éditeur de texte.
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é.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Paramètre de chemin.
Pour Chemin, entrez un chemin.
Pour Méthode, sélectionnez un HTTP verbe.
Pour Nom, entrez un nom.
Entrez une description dans l'éditeur de texte.
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un paramètre de chemin non répertorié.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez En-tête de demande.
Pour Chemin, entrez un chemin pour l'en-tête de demande.
Pour Méthode, sélectionnez un HTTP verbe.
Pour Nom, entrez un nom.
Entrez une description dans l'éditeur de texte.
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é.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Corps de la demande.
Pour Chemin, entrez un chemin pour le corps de la demande.
Pour Méthode, sélectionnez un HTTP verbe.
Entrez une description dans l'éditeur de texte.
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un corps de la demande non répertorié.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
Choisissez Modifier.
Documentation d'une entité RESPONSE
Pour ajouter une nouvelle partie de la documentation pour une entité RESPONSE
, procédez comme suit :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Réponse (code de statut).
Pour Chemin, entrez un chemin pour la réponse.
Pour Méthode, sélectionnez un HTTP verbe.
Pour le code d'état, entrez un code d'HTTPétat.
Entrez une description dans l'éditeur de texte.
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é.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez En-tête de réponse.
Pour Chemin, entrez un chemin pour l'en-tête de réponse.
Pour Méthode, sélectionnez un HTTP verbe.
Pour le code d'état, entrez un code d'HTTPétat.
Entrez une description dans l'éditeur de texte.
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é.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Corps de la réponse.
Pour Chemin, entrez un chemin pour le corps de la réponse.
Pour Méthode, sélectionnez un HTTP verbe.
Pour le code d'état, entrez un code d'HTTPétat.
Entrez une description dans l'éditeur de texte.
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour un corps de réponse non répertorié.
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 :
Dans le volet Documentation, choisissez l'onglet Ressources et méthodes.
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.
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, car le Error
modèle fourni avec chaque API par défaut possède 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 le API est exporté, les propriétés DocumentationPart
du remplacent les valeurs du schéma d'origine.
Pour ajouter une nouvelle partie de la documentation pour une entité MODEL
, procédez comme suit :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Modèle.
Pour Nom, entrez un nom pour le modèle.
Entrez une description dans l'éditeur de texte.
Choisissez Créer une partie de la documentation. Vous pouvez créer de la documentation pour des modèles non répertoriés.
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 :
Dans le volet de navigation principal, choisissez Modèles.
Choisissez le modèle, puis Mettre à jour la documentation.
Pour modifier une partie de la documentation existante, procédez comme suit :
Dans le volet Documentation, choisissez l'onglet Modèles.
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 :
Dans le volet de navigation principal, choisissez Documentation, puis Créer une partie de la documentation.
Pour Type de documentation, sélectionnez Mécanisme d'autorisation.
Pour Nom, entrez le nom de votre mécanisme d'autorisation.
Entrez une description dans l'éditeur de texte. Spécifiez une valeur pour le champ
location
valide pour le mécanisme d'autorisation.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.
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 :
Dans le volet Documentation, choisissez l'onglet Mécanismes d'autorisation.
Utilisez la barre de recherche ou sélectionnez le mécanisme d'autorisation, puis choisissez Modifier.