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.
Publiez de API la documentation à l'aide de la API passerelle REST API
Pour publier la documentation d'uneAPI, créer, mettre à jour ou obtenir un instantané de documentation, puis associer l'instantané de documentation à une API étape. Lorsque vous créez un instantané de documentation, vous pouvez également l'associer à une API étape en même temps.
Rubriques
- Créez un instantané de documentation et associez-le à une API étape
- Création d'un instantané de documentation
- Mise à jour d'un instantané de documentation
- Obtention d'un instantané de documentation
- Associer un instantané de documentation à une API étape
- Téléchargement d'un instantané de documentation associé à une étape
Créez un instantané de documentation et associez-le à une API étape
Pour créer un instantané des parties API de la documentation d'un utilisateur et l'associer à une API étape en même temps, soumettez la POST
demande suivante :
POST /restapis/
restapi_id
/documentation/versions HTTP/1.1 Host: apigateway.region
.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZ
Authorization: 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.
Vous pouvez également créer un instantané de documentation sans l'associer d'abord à une API étape, puis appeler restapi:update pour associer l'instantané à une étape spécifiée. 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é des parties API de la documentation d'un utilisateur, créez une nouvelle DocumentationVersionressource et ajoutez-la à la DocumentationVersionscollection des API :
POST /restapis/
restapi_id
/documentation/versions HTTP/1.1 Host: apigateway.region
.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZ
Authorization: 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 ne pouvez mettre à jour un instantané de documentation qu'en modifiant la description
propriété de la DocumentationVersionressource correspondante. L'exemple suivant montre comment mettre à jour la description de l'instantané de la documentation tel qu'identifié par son identifiant de version,
, par exemple, version
1.0.0
.
PATCH /restapis/
restapi_id
/documentation/versions/version
HTTP/1.1 Host: apigateway.region
.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZ
Authorization: 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
Pour obtenir un instantané de la documentation, soumettez une GET
demande pour la DocumentationVersionressource 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:YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id
/YYYYMMDD
/region
/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
Associer un instantané de documentation à une API étape
Pour publier la API documentation, associez un instantané de documentation à une API étape. Vous devez avoir déjà créé une API étape avant d'associer la version de documentation à l'étape.
Pour associer un instantané de documentation à une API étape à l'aide de la APIpasserelle REST API, appelez l'opération stage:update pour définir la version de documentation souhaitée sur la propriété : stage.documentationVersion
PATCH /restapis/
RESTAPI_ID
/stages/STAGE_NAME
Host: apigateway.region
.amazonaws.com Content-Type: application/json X-Amz-Date:YYYYMMDDTttttttZ
Authorization: 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 des API entités vers un fichier externe, à l'aide de la console API Gateway, de la API passerelle RESTAPI, de l'une de ses SDKs versions ou de la API passerelle AWS CLI for Gateway. Le processus est le même que pour l'exportation duAPI. Le format de fichier exporté peut être JSON ouYAML.
À l'aide de la API passerelle RESTAPI, vous pouvez également définir explicitement le paramètre de extension=documentation,integrations,authorizers
requête pour inclure les parties de la API documentation, API les intégrations et les autorisateurs dans une API exportation. Par défaut, les parties de la documentation sont incluses, mais les intégrations et les autorisateurs sont exclus lorsque vous exportez un. API La sortie par défaut d'une API exportation est adaptée à la distribution de la documentation.
Pour exporter la API documentation dans un API fichier JSON ouvert externe à l'aide de la API passerelle RESTAPI, soumettez la GET
demande 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:YYYYMMDDTttttttZ
Authorization: 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'x-amazon-apigateway-documentation
objet contient les parties de la documentation et les définitions des API entités contiennent les propriétés de 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'Accept:application/json
en-tête de la demande pour afficher le résultat dans un JSON fichier. Pour produire la YAML sortie, remplacez l'en-tête de la demande parAccept:application/yaml
.
À titre d'exemple, nous allons examiner un API qui expose une GET
méthode simple sur la ressource racine (/
). Quatre API entités sont définies dans un fichier de API définition ouvert, une pour chacun des RESPONSE
types API
MODEL
METHOD
,, et. API 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 le résultat suivant, avec les parties de la documentation répertoriées dans l'x-amazon-apigateway-documentation
objet en tant qu'extension d'un fichier Open API standard.
Pour un attribut API compatible Open défini dans la properties
carte d'une partie de documentation, API Gateway insère l'attribut dans la définition d'APIentité associée. Un attribut de x-
est une API extension Open standard. Cette extension est propagée dans la définition de l'APIentité. Par exemple, consultez l'attribut something
x-example
pour la méthode GET
. Un attribut tel ne foo
fait pas partie de la API spécification Open et n'est pas injecté dans les définitions d'APIentités associées.
Si un outil de rendu de documentation (par exemple, Open API UIproperties
à Open d'une instance DocumentationPart
'ne sont pas disponibles pour l'outil. Toutefois, si un outil de rendu de documentation analyse l'x-amazon-apigateway-documentation
objet pour obtenir du contenu, ou s'il appelle restapi:documentation-parts et documentationpart:by-id pour récupérer des parties de documentation depuis API Gateway, tous les attributs de documentation sont disponibles pour l'affichage par l'outil.
Pour exporter la documentation contenant les définitions d'APIentités contenant les détails de l'intégration vers un API fichier JSON Open, soumettez la GET
demande 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:YYYYMMDDTttttttZ
Authorization: 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 contenant les définitions d'APIentités contenant les détails des intégrations et des autorisateurs vers un API fichier YAML Open, soumettez la demande suivante : GET
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:YYYYMMDDTttttttZ
Authorization: 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'unAPI, suivez les instructions figurant dansExporter REST API à l'aide de la console API Gateway.