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 x-amazon-apigateway-documentation objeto 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. 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/<restapi_id>/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/<restapi_id>/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 ou restapi:put, 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.

2. Escolha Importar.

3. Se você já tiver uma documentação, selecione Substituir ou Mesclar a nova documentação.

4. 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.

5. 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 durante a importação.

6. Escolha Import.