# Importar la documentación de API
De igual modo que para importar definiciones de entidad de API, puede importar piezas de documentación de un archivo de OpenAPI externo a una API mediante API Gateway. Las piezas de documentación que se van a importar se especifican en la extensión [Objeto x-amazon-apigateway-documentation](api-gateway-swagger-extensions-documentation.md) en un archivo de definición de OpenAPI válido. La importación de la documentación no modifica las definiciones de entidad de API existentes.
Tiene la opción de combinar las piezas de documentación recién especificadas en piezas de documentación existentes en API Gateway o de sobrescribir las piezas de documentación existentes. En el modo `MERGE`, una nueva pieza de documentación definida en el archivo de OpenAPI se añade a la colección `DocumentationParts` de la API. Si ya existe un elemento `DocumentationPart` importado, el atributo importado reemplaza al existente si los dos son diferentes. Todos los demás atributos de documentación existentes permanecen tal como están. En el modo `OVERWRITE`, toda la colección `DocumentationParts` se reemplaza de acuerdo con el archivo de definición de OpenAPI importado.
## Importar piezas de documentación mediante la API de REST de API Gateway
Para importar la documentación de API mediante la API de REST de API Gateway, llame a la operación [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). En el siguiente ejemplo, se muestra cómo sobrescribir las piezas de documentación existentes de una API con un único método `GET / `, que devuelve una respuesta `200 OK` si se ejecuta correctamente.
------
#### [ 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"
}
}
]
}
}
```
------
Cuando se ejecuta correctamente, esta solicitud devuelve una respuesta 200 OK que contiene el elemento `DocumentationPartId` importado en la carga.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
Además, también puede llamar a [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) o [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html), proporcionando las piezas de documentación en el objeto `x-amazon-apigateway-documentation` como parte del archivo de OpenAPI de entrada de la definición de la API. Para excluir piezas de documentación de la importación de API, establezca `ignore=documentation` en los parámetros de consulta de la solicitud.
## Importar piezas de documentación mediante la consola de API Gateway
Las siguientes instrucciones describen cómo importar piezas de documentación.
**Para utilizar la consola para importar piezas de documentación de una API desde un archivo externo**
1. En el panel de navegación principal, elija **Documentación**.
1. Seleccione **Importar**.
1. Si ya tiene documentación, seleccione **Sobrescribir** o **Fusionar** la nueva documentación.
1. Elija **Seleccionar archivo** para cargar un archivo de una unidad, o ingrese el contenido del archivo en la vista de archivos. Para ver un ejemplo, consulte la carga de la solicitud de ejemplo de [Importar piezas de documentación mediante la API de REST de API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api).
1. Elija cómo gestionar las advertencias durante la importación. Seleccione **Error en advertencias** o **Ignorar advertencias**. Para obtener más información, consulte [Errores y advertencias al importar la API a API Gateway](api-gateway-import-api-errors-warnings.md).
1. Seleccione **Importar**.