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.
**Topics**
+ [Création d’un instantané de la documentation et association à une étape de l’API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Création d’un instantané de documentation](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Mise à jour d’un instantané de documentation](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Obtention d’un instantané de documentation](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Association d’un instantané de documentation avec une étape d’API](#api-gateway-documenting-api-publishing-stage-association)
+ [Téléchargement d’un instantané de documentation associé à une étape](#api-gateway-documenting-api-publishing-export-documentation-version)
## 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: 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.
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](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) 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é des parties de la documentation d'une API, créez une nouvelle [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)ressource et ajoutez-la à la [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)collection de l'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 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)ressource correspondante. L’exemple suivant montre comment mettre à jour la description de l’instantané de la documentation tel qu’identifié par son identifiant de version, `version`, par exemple, `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 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)ressource spécifiée. L’exemple suivant montre comment obtenir un instantané de documentation d’un identifiant de version donné, 1.0.0.
```
GET /restapis//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
```
## 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](https://docs.aws.amazon.com/apigateway/latest/api/), appelez l’opération [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) afin de définir la version souhaitée de la documentation 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 ainsi que les définitions des entités d'API, vers un fichier externe, à l'aide de la console API Gateway, de l'API REST API Gateway, de l'une de ses SDKs API ou de l'API Gateway AWS CLI for. 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: 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’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ée). 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`.
À 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.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
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-something` est une extension OpenAPI standard. Cette extension est appliquée à la définition de l’entité d’API. Par exemple, consultez l’attribut `x-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 UI](https://swagger.io/tools/swagger-ui/)) analyse les définitions de l’entité d’API afin d’extraire les attributs de la documentation, tout attribut `properties` 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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) et [documentationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) 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: 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 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: 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’une API, suivez les instructions de [Exportation d'une API REST à l'aide de la console API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console).