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.
Publication de la documentation de l'API à l'aide de l'API REST
Pour publier la documentation d'une API, créez, mettez à jour ou obtenez l'instantané de la documentation, puis associez-le à une étape de l'API. Lorsque vous créez un instantané de documentation, vous pouvez également l'associer à une étape de l'API en même temps.
Rubriques
- Création d'un instantané de la documentation et association à une étape de l'API
- Création d'un instantané de documentation
- Mise à jour d'un instantané de documentation
- Obtention d'un instantané de documentation
- Association d'un instantané de documentation avec une étape d'API
- Téléchargement d'un instantané de documentation associé à une étape
Création d'un instantané de la documentation et association à une étape de l'API
Pour créer un instantané de certaines parties de la documentation de l'API et l'associer à une étape de l'API en même temps, soumettez la demande POST suivante :
POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "documentationVersion" : "1.0.0", "stageName": "prod", "description" : "My API Documentation v1.0.0" }
Si l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion nouvellement créée en tant que charge utile.
Sinon, vous pouvez créer un instantané de la documentation sans l'associer à une étape de l'API en premier lieu, puis appeler restapi:update pour associer cet instantané à une étape de l'API. Vous pouvez également mettre à jour ou interroger un instantané de documentation existant, puis mettre à jour son association à une étape donnée. Nous présentons les étapes correspondantes au cours des quatre sections suivantes.
Création d'un instantané de documentation
Pour créer un instantané de parties de la documentation de l'API, créez une ressource DocumentationVersion et ajoutez-la à la collection DocumentationVersions de l'API :
POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "documentationVersion" : "1.0.0", "description" : "My API Documentation v1.0.0" }
Si l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion nouvellement créée en tant que charge utile.
Mise à jour d'un instantané de documentation
Vous pouvez uniquement mettre à jour un instantané de documentation en modifiant la propriété description de la ressource DocumentationVersion correspondante. L'exemple suivant montre comment mettre à jour la description de l'instantané de la documentation tel qu'identifié par son identifiant de version, version1.0.0.
PATCH /restapis/restapi_id/documentation/versions/versionHTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "patchOperations": [{ "op": "replace", "path": "/description", "value": "My API for testing purposes." }] }
Si l'opération réussit, elle renvoie une réponse 200 OK, contenant l'instance DocumentationVersion mise à jour en tant que charge utile.
Obtention d'un instantané de documentation
Afin d'obtenir un instantané de documentation, soumettez une demande GET par rapport à la ressource DocumentationVersion spécifiée. L'exemple suivant montre comment obtenir un instantané de documentation d'un identifiant de version donné, 1.0.0.
GET /restapis/<restapi_id>/documentation/versions/1.0.0 HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
Association d'un instantané de documentation avec une étape d'API
Pour publier la documentation d'une API, associez un instantané de documentation à une étape de l'API. Vous devez déjà avoir déjà une étape de l'API avant d'associer la version de la documentation à l'étape.
Pour associer un instantané de documentation à une étape d'API à l'aide de l'API REST API Gateway, appelez l'opération stage:update afin de définir la version souhaitée de la documentation sur la propriété stage.documentationVersion :
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAMEHost: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret{ "patchOperations": [{ "op": "replace", "path": "/documentationVersion", "value": "VERSION_IDENTIFIER" }] }
Téléchargement d'un instantané de documentation associé à une étape
Une fois qu'une version des parties de la documentation est associée à une étape, vous pouvez exporter les parties de la documentation avec les définitions d'entités API vers un fichier externe à l'aide de la console API Gateway, de l'API REST API Gateway, de l'un de ses kits SDK ou de la AWS CLI pour API Gateway. Le processus est le même que pour l'exportation de l'API. Le format de fichier exporté peut être JSON ou YAML.
À l'aide de l'API REST API Gateway, vous pouvez aussi définir explicitement le paramètre de requête extension=documentation,integrations,authorizers afin d'inclure les parties de la documentation de l'API, les intégrations de l'API et les mécanismes d'autorisation dans le cadre d'une exportation de l'API. Par défaut, les parties de la documentation sont incluses, mais les intégrations et les mécanismes d'autorisation sont exclus, lorsque vous exportez une API. La sortie par défaut d'une exportation d'API convient à la distribution de la documentation.
Pour exporter la documentation de l'API dans un fichier OpenAPI JSON externe en utilisant l'API REST API Gateway, envoyez la demande GET suivante :
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
Ici, l'objet x-amazon-apigateway-documentation contient les parties de la documentation et les définitions d'entités d'API contiennent les propriétés de la documentation prises en charge par OpenAPI. Le résultat n'inclut pas les détails de l'intégration ou des mécanismes d'autorisation Lambda (anciennement appelés mécanismes d'autorisation personnalisés). Pour inclure les deux détails, définissez extensions=integrations,authorizers,documentation. Pour inclure les détails des intégrations, mais pas les mécanismes d'autorisation, définissez extensions=integrations,documentation.
Vous devez définir l'en-tête Accept:application/json dans la demande pour faire sortir le résultat dans un fichier JSON. Pour produire la sortie YAML, modifiez l'en-tête de la requête sur Accept:application/yaml.
A titre d'exemple, nous allons étudier une API qui expose une méthode GET simple sur la ressource racine (/). Cette API a quatre entités d'API définies dans un fichier de définition OpenAPI, une pour chaque type API, MODEL, METHOD et RESPONSE. Une partie de la documentation a été ajoutée à chaque entité API, METHOD et RESPONSE. En appelant la commande d'exportation de documentation précédente, nous obtenons la sortie suivante, avec les parties de la documentation répertoriées dans l'objet x-amazon-apigateway-documentation sous forme d'extension d'un fichier OpenAPI standard.
Pour un attribut compatible à OpenAPI défini dans le mappage properties d'une partie de la documentation, API Gateway insère l'attribut dans la définition d'entité API associée. Un attribut x- est une extension OpenAPI standard. Cette extension est appliquée à la définition de l'entité d'API. Par exemple, consultez l'attribut somethingx-example pour la méthode GET. Un attribut tel que foo ne fait pas partie de la spécification OpenAPI et n'est pas injecté dans les définitions de l'entité d'API associées.
Si un outil de rendu de documentation (par exemple, OpenAPI UIproperties non conforme à OpenAPI d'une instance DocumentationPart n'est pas disponible pour l'outil. Toutefois, si un outil de rendu de documentation analyse l'objet x-amazon-apigateway-documentation pour obtenir le contenu ou si l'outil appelle restapi:documentation-parts et documentationpart:by-id pour récupérer des parties de la documentation API Gateway, tous les attributs de documentation sont disponibles et peuvent être affichés par l'outil.
Pour exporter la documentation avec les définitions d'entité d'API contenant les détails de l'intégration dans un fichier JSON OpenAPI, envoyez la requête GET suivante :
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
Pour exporter la documentation avec les définitions d'entité d'API contenant les détails d'intégration et les mécanismes d'autorisation dans un fichier OpenAPI YAML, envoyez la requête GET suivante :
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1 Accept: application/yaml Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZAuthorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
Pour utiliser la console API Gateway afin d'exporter et de télécharger la documentation publiée d'une API, suivez les instructions de Exportation d'une API REST à l'aide de la console API Gateway.
