# Importar a documentação da API
Como na importação de definições de entidades de API, você pode importar partes de documentação de um arquivo externo do OpenAPI para uma API no API Gateway. Especifique as partes de documentação a serem importadas dentro da extensão [Objeto x-amazon-apigateway-documentation](api-gateway-swagger-extensions-documentation.md) em um arquivo de definição do OpenAPI válido. Importar a documentação não altera as definições de entidades de API existentes.
Você tem a opção de mesclar as partes de documentação recém-especificadas em partes de documentação existentes no API Gateway ou de substituir as partes de documentação existentes. No modo `MERGE`, uma nova parte de documentação definida no arquivo do OpenAPI é adicionada à coleção `DocumentationParts` da API. Se uma `DocumentationPart` importada já existir, um atributo importado substituirá o existente caso os dois sejam diferentes. Outros atributos de documentação existentes permanecem inalterados. No modo `OVERWRITE`, a coleção `DocumentationParts` inteira é substituída de acordo com o arquivo de definição do OpenAPI importado.
## Importar partes de documentação com a API REST do API Gateway
Para importar a documentação da API usando a API REST do API Gateway, chame a operação [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). O exemplo a seguir mostra como substituir partes de documentação existentes de uma API por um único método `GET / `, retornando uma resposta `200 OK` em caso de êxito.
------
#### [ 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"
}
}
]
}
}
```
------
Quando bem-sucedida, essa solicitação retorna uma resposta 200 OK contendo o `DocumentationPartId` importado na carga.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
Além disso, você também pode chamar [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), fornecendo as partes de documentação no objeto `x-amazon-apigateway-documentation` como parte do arquivo de entrada do OpenAPI da definição da API. Para excluir as partes de documentação da importação da API, defina `ignore=documentation` nos parâmetros da consulta de solicitação.
## Importar partes de documentação com o console do API Gateway
As instruções a seguir descrevem como importar partes de documentação.
**Para usar o console de modo a importar partes de documentação de uma API a partir de um arquivo externo**
1. No painel de navegação principal, escolha **Documentação**.
1. Escolha **Importar**.
1. Se você já tiver uma documentação, selecione **Substituir** ou **Mesclar** a nova documentação.
1. Selecione **Escolher arquivo** para carregar um arquivo de uma unidade ou insira o conteúdo do arquivo na exibição de arquivo. Para conhecer um exemplo, veja a carga da solicitação de exemplo em [Importar partes de documentação com a API REST do API Gateway](#api-gateway-importing-api-with-swagger-file-using-rest-api).
1. Escolha como lidar com os avisos na importação. Selecione **Falhar nos avisos** ou **Ignorar avisos**. Para obter mais informações, consulte [Erros e avisos ao importar a API para o API Gateway](api-gateway-import-api-errors-warnings.md).
1. Escolha **Importar**.