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.
# Importation de la documentation d’une API
Comme avec l’importation des définitions d’entités d’API, vous pouvez importer les parties de la documentation d’un fichier OpenAPI externe vers une API dans API Gateway. Vous spécifiez les parties de la to-be-imported documentation au sein de l'[x-amazon-apigateway-documentation objet](api-gateway-swagger-extensions-documentation.md)extension dans un fichier de définition OpenAPI valide. L’importation de la documentation ne modifie pas les définitions d’entités d’API existantes.
Vous avez la possibilité de fusionner les parties de la documentation nouvellement spécifiées avec les parties de la documentation existantes dans API Gateway ou de remplacer les parties existantes de la documentation. En mode `MERGE`, une nouvelle partie de la documentation définie dans le fichier OpenAPI est ajoutée à la collection `DocumentationParts` de l’API. Si une `DocumentationPart` importée existe déjà, un attribut importé remplace celui qui existe déjà si les deux sont différents. Les autres attributs de documentation existants ne sont pas modifiés. En mode `OVERWRITE`, toute la collection `DocumentationParts` est remplacée selon le fichier de définition OpenAPI importé.
## Importation de parties de la documentation à l’aide de l’API REST API Gateway
Pour importer la documentation de l’API en utilisant l’API REST API Gateway, appelez l’opération [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). L’exemple suivant montre comment remplacer les parties de documentation existantes d’une API par une seule méthode `GET / `, en renvoyant une réponse `200 OK` en cas de réussite.
------
#### [ OpenAPI 3.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
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
{
"openapi": "3.0.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
}
}
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
},
"servers": [
{
"url": "/"
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
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
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"host": "",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"description": "Method description.",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
}
}
```
------
En cas de réussite, cette demande renvoie une réponse 200 OK contenant la `DocumentationPartId` importée dans la charge utile.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
En outre, vous pouvez également appeler [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) ou [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html) en fournissant les parties de la documentation dans l’objet `x-amazon-apigateway-documentation`, dans le cadre du fichier d’entrée OpenAPI de la définition d’API. Pour exclure les parties de la documentation de l’importation de l’API, définissez `ignore=documentation` dans les paramètres de la demande.
## Importation de parties de la documentation avec la console API Gateway
Les instructions suivantes expliquent comment importer des parties de la documentation.
**Pour utiliser la console afin d’importer des parties de la documentation d’une API à partir d’un fichier externe**
1. Dans le volet de navigation principal, choisissez **Documentation**.
1. Choisissez **Importer**.
1. Si vous avez de la documentation existante, sélectionnez **Remplacer** ou **Fusionner** votre nouvelle documentation.
1. Choisissez **Choisir un fichier** pour charger un fichier à partir d’un lecteur ou entrez le contenu d’un fichier dans l’affichage de fichier. Pour obtenir un exemple, consultez la charge utile de l’exemple de demande dans [Importation de parties de la documentation à l’aide de l’API REST API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api).
1. Choisissez comment gérer les avertissements lors de l’importation. Sélectionnez **Échouer avec les avertissements** ou **Ignorer les avertissements**. Pour de plus amples informations, veuillez consulter [Erreurs et avertissements liés à l’importation de votre API dans API Gateway](api-gateway-import-api-errors-warnings.md).
1. Choisissez **Importer**.