# Desenvolver APIs REST usando OpenAPI no API Gateway Você pode usar o API Gateway para importar uma API REST de um arquivo de definição externo para o API Gateway. No momento, o API Gateway é compatível com arquivos de definição [v2.0 da OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) e [v3.0 da OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), com exceções listadas em [Notas importantes do Amazon API Gateway para APIs REST](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). É possível atualizar uma API substituindo-a por uma nova definição ou mesclar uma definição com uma API existente. As opções são especificadas usando um parâmetro de consulta `mode` no URL solicitado. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API otimizada para bordas para o API Gateway](import-edge-optimized-api.md) + [Importar uma API regional para o API Gateway](import-export-api-endpoints.md) + [Importar um arquivo do OpenAPI para atualizar uma definição de API existente](api-gateway-import-api-update.md) + [Defina a propriedade `basePath` OpenAPI](api-gateway-import-api-basePath.md) + [Variáveis da AWS para importação de OpenAPI](import-api-aws-variables.md) + [Erros e avisos ao importar a API para o API Gateway](api-gateway-import-api-errors-warnings.md) + [Exportar uma API REST do API Gateway](api-gateway-export-api.md) # Importar uma API otimizada para bordas para o API Gateway Você pode importar um arquivo de definição do OpenAPI de uma API para criar uma nova API otimizada para fronteiras especificando o tipo de endpoint `EDGE` como uma entrada adicional, além do arquivo do OpenAPI, para a operação de importação. É possível fazer isso usando o console do API Gateway, a AWS CLI ou um AWS SDK. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API otimizada para bordas usando o console do API Gateway](#import-edge-optimized-api-with-console) + [Importar uma API otimizada para bordas usando a AWS CLI](#import-edge-optimized-api-with-awscli) ## Importar uma API otimizada para bordas usando o console do API Gateway Para importar uma API otimizada para bordas usando o console do API Gateway, faça o seguinte: 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione **Create API** (Criar API). 1. Em **REST API** (API REST), escolha **Import** (Importar). 1. Copie uma definição do OpenAPI da API e cole-a no editor de código ou selecione **Escolher arquivo** para carregar um arquivo do OpenAPI de uma unidade local. 1. Em **Tipo de endpoint da API**, escolha **Otimizado para borda**. 1. Escolha **Criar API** para começar a importar as definições do OpenAPI. ## Importar uma API otimizada para bordas usando a AWS CLI O comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) indicado abaixo importa uma API do arquivo de definição do OpenAPI para criar uma API otimizada para borda: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` ou com uma especificação explícita do parâmetro de string de consulta `endpointConfigurationTypes` para `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importar uma API regional para o API Gateway Ao importar uma API, você pode escolher a configuração de endpoint regional para a API. É possível usar o console do API Gateway, a AWS CLI ou um AWS SDK. Ao exportar uma API, a configuração de endpoint da API não está incluído nas definições da API exportada. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API regional usando o console do API Gateway](#import-regional-api-with-console) + [Importar uma API regional usando a AWS CLI](#import-regional-api-with-awscli) ## Importar uma API regional usando o console do API Gateway Para importar uma API de um endpoint regional usando o console do API Gateway, faça o seguinte: 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione **Create API** (Criar API). 1. Em **REST API** (API REST), escolha **Import** (Importar). 1. Copie uma definição do OpenAPI da API e cole-a no editor de código ou selecione **Escolher arquivo** para carregar um arquivo do OpenAPI de uma unidade local. 1. Em **Tipo de endpoint da API**, escolha **Regional**. 1. Escolha **Criar API** para começar a importar as definições do OpenAPI. ## Importar uma API regional usando a AWS CLI O comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) indicado abaixo importa um arquivo de definição OpenAPI e define o tipo de endpoint como regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importar um arquivo do OpenAPI para atualizar uma definição de API existente Você pode importar as definições de APIs apenas para atualizar uma API existente, sem alterar sua configuração de endpoint, bem como os estágios e suas variáveis ou referências a chaves de APIs. A operação de importação para atualização pode ocorrer em dois modos: mesclagem ou substituição. Quando uma API (`A`) é mesclada com outra (`B`), a API resultante retém as definições de `A` e `B`, se as duas APIs não compartilharem definições conflitantes. Em caso de conflito, as definições de método da API de mesclagem (`A`) substituem as definições de método correspondentes da API mesclada (`B`). Por exemplo, suponha que `B` tenha declarado os seguintes métodos para retornar as respostas `200` e `206`: ``` GET /a POST /a ``` e que `A` declare o seguinte método para retornar as respostas `200` e `400`: ``` GET /a ``` Quando `A` é mesclada com `B`, a API resultante produz os seguintes métodos: ``` GET /a ``` que retorna `200` e `400` respostas e ``` POST /a ``` que retorna `200` e `206` respostas. A mesclagem de uma API é útil quando você decompôs suas definições de API externas em várias partes menores e apenas deseja aplicar as alterações de uma dessas partes de cada vez. Por exemplo, isso pode ocorrer se várias equipes são responsáveis por diferentes partes de uma API e têm alterações disponíveis em ritmos diferentes. Nesse modo, os itens da API existente que não estiverem especificamente indicados na definição importada serão ignorados. Quando uma API (`A`) substitui outra API (`B`), a API resultante assume as definições da API de substituição (`A`). A substituição de uma API é útil quando uma definição de API externa contém a definição completa de uma API. Nesse modo, os itens de uma API existente que não estiverem especificamente indicados na definição importada serão excluídos. Para mesclar uma API, envie uma solicitação `PUT` para `https://apigateway..amazonaws.com/restapis/?mode=merge`. O valor do parâmetro do caminho `restapi_id` especifica a API com a qual a definição de API fornecida será mesclada. O seguinte trecho de código mostra um exemplo da solicitação `PUT` para mesclar uma definição de API do OpenAPI em JSON, como a carga útil, com a API especificada já no API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` A operação de atualização se mesclagem usa duas definições de API completas e as mescla em uma só. Para uma alteração pequena e incremental, você pode usar a operação de [atualização de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Para substituir uma API, envie uma solicitação `PUT` para `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. O parâmetro de caminho `restapi_id` especifica a API que será substituída pelas definições de API fornecidas. O seguinte trecho de código mostra um exemplo de uma solicitação de substituição com a carga de uma definição do OpenAPI formatada em JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Quando o parâmetro de consulta `mode` não é especificado, supõe-se uma mesclagem. **nota** As operações `PUT` são idempotentes, mas não atômicas. Isso significa que, se um erro de sistema ocorrer no meio do processamento, a API poderá terminar em mau estado. No entanto, repetir a operação com êxito coloca a API no mesmo estado final, como se a primeira operação tivesse sido bem-sucedida. # Defina a propriedade `basePath` OpenAPI No [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), você pode usar a propriedade `basePath` para fornecer uma ou mais partes de caminhos que precedem cada caminho definido na propriedade `paths`. Como o API Gateway tem várias maneiras de expressar um caminho de um recurso, o recurso Import API (Importar API) fornece as seguintes opções para interpretar a propriedade `basePath` durante uma importação: ignorar, preceder e dividir. No [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` não é mais uma propriedade de nível superior. Em vez disso, o API Gateway usa uma [variável de servidor](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) como convenção. O recurso Import API (Importar API) fornece as mesmas opções para interpretar o caminho base durante a importação. O caminho base é identificado da seguinte forma: + Se a API não contém variáveis `basePath`, o recurso Import API (Importar API) verifica a string `server.url` para conferir se ela contém um caminho além de `"/"`. Se sim, esse caminho será usado como caminho base. + Se a API contém apenas uma variável `basePath`, o recurso Import API (Importar API) a usa como caminho base, mesmo que ela não seja indicada no `server.url`. + Se a API contém várias variáveis `basePath`, o recurso Import API (Importar API) usa apenas a primeira como caminho base. ## Ignorar Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c`, e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` resultará nos seguintes recursos na API: + `/` + `/e` + `/f` O efeito é tratar `basePath` como se ele não estivesse presente, e todos os recursos da API declarados são atendidos em relação ao host. Isso pode ser usado, por exemplo, quando você tem um nome de domínio personalizado com um mapeamento de API que não inclui um *caminho base* e um valor de *estágio* que faz referência ao seu estágio de produção. **nota** O API Gateway cria automaticamente um recurso raiz para você, mesmo que ele não esteja explicitamente declarado no seu arquivo de definição. Quando não especificado, o `basePath` pega `ignore` por padrão. ## Preceder Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c` e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` resultará nos seguintes recursos na API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` O efeito é tratar `basePath` como se recursos adicionais estivessem sendo especificados (sem métodos) e adicioná-los ao conjunto de recursos declarados. Isso pode ser usado, por exemplo, quando diferentes equipes são responsáveis por diferentes partes de uma API e o `basePath` pode fazer referência ao local do caminho para a parte da API de cada equipe. **nota** O API Gateway cria recursos intermediários automaticamente para você, mesmo que eles não estejam explicitamente declarados na sua definição. ## Split Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c` e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` resultará nos seguintes recursos na API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` O efeito é tratar a parte do caminho mais no início, `/a`, como o início do caminho de cada recurso e criar recursos adicionais (sem método) na própria API. Isso pode ser usado, por exemplo, quando `a` é um nome de estágio que deseja expor como parte da sua API. # Variáveis da AWS para importação de OpenAPI Você pode usar as seguintes variáveis da AWS nas definições do OpenAPI. O API Gateway resolve as variáveis quando a API é importada. Para especificar uma variável, use `${variable-name}`. A tabela a seguir descreve as estatísticas da AWS disponíveis. | Nome da variável | Descrição | | --- | --- | | AWS::AccountId | O ID da conta AWS que importa a API. Por exemplo, 123456789012. | | AWS::Partition | A partição da AWS na qual a API é importada. Para regiões padrão da AWS a partição é aws. | | AWS::Region | A região da AWS na qual a API é importada. Por exemplo, us-east-2. | ## Exemplo de variáveis da AWS O exemplo a seguir usa variáveis da AWS para especificar uma função do AWS Lambda para uma integração. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Erros e avisos ao importar a API para o API Gateway Ao importar o arquivo de definição externo para o API Gateway, ele pode gerar avisos e erros. As seções a seguir explicam os erros e os avisos que podem ocorrer durante a importação. ## Erros durante a importação Durante a importação, erros podem ser gerados para problemas importantes, como um documento inválido do OpenAPI. Os erros são retornados como exceções (por exemplo, `BadRequestException`) em uma resposta mal-sucedida. Quando ocorre um erro, a nova definição da API é descartada, e nenhuma alteração é feita na API existente. ## Avisos durante a importação Durante a importação, avisos podem ser gerados para problemas menores, como uma referência de modelo ausente. Se um aviso ocorrer, a operação continuará se a expressão de consulta `failonwarnings=false` for acrescentada à URL da solicitação. Caso contrário, as atualizações serão revertidas. Por padrão, `failonwarnings` é definido como `false`. Nesses casos, os avisos são retornados como um campo no recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resultante. Caso contrário, os avisos serão retornados como uma mensagem na exceção. # Exportar uma API REST do API Gateway Depois de criar e configurar uma API REST no API Gateway, usando o console do API Gateway ou de outra forma, você pode exportá-la para um arquivo OpenAPI usando a API de exportação do API Gateway, que faz parte do Amazon API Gateway Control Service. Para usar a API de exportação do API Gateway, você precisa assinar suas solicitações de API. Para ter mais informações sobre como assinar solicitações, consulte [Assinar solicitações de API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) no *Guia do usuário do IAM*. Existem opções para incluir as extensões de integração do API Gateway, bem como as extensões do [Postman](https://www.postman.com), no arquivo de definição do OpenAPI exportado. **nota** Ao exportar a API usando a AWS CLI, inclua o parâmetro de extensões, conforme mostrado no exemplo a seguir, para garantir que a extensão `x-amazon-apigateway-request-validator` seja incluída: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Não será possível exportar uma API se suas cargas não forem do tipo `application/json`. Se você tentar, receberá uma resposta de erro indicando que os modelos de corpo JSON não foram encontrados. ## Solicitar a exportação de uma API REST Com o recurso Export API, você exporta uma API REST existente ao enviar uma solicitação GET, especificando a API a ser exportada como parte de caminhos de URL. A URL da solicitação tem o seguinte formato: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Você pode acrescentar a string de consulta `extensions` para especificar se deseja incluir extensões do API Gateway (com o valor `integration`) ou extensões do Postman (com o valor `postman`). Além disso, é possível definir o cabeçalho `Accept` como `application/json` ou `application/yaml` para receber a saída da definição de API no formato JSON ou YAML, respectivamente. Para obter mais informações sobre como enviar solicitações GET usando a API Export do API Gateway, consulte [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **nota** Se você definir modelos na sua API, eles deverão ser destinados ao tipo de conteúdo “application/json” para que o API Gateway exporte o modelo. Caso contrário, o API Gateway lançará uma exceção com a mensagem de erro de que apenas modelos de corpo não JSON foram encontrados. Os modelos devem conter propriedades ou serem definidos como um determinado tipo de JSONSchema. ## Fazer download da definição da API REST do OpenAPI em JSON Para exportar e fazer download de uma API REST em definições do OpenAPI no formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Aqui, `` poderia ser, por exemplo, `us-east-1`. Para conhecer todas as regiões onde o API Gateway está disponível, consulte [Regiões e endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Fazer download da definição da API REST do OpenAPI em YAML Para exportar e fazer download de uma API REST em definições do OpenAPI no formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Fazer download da definição da API REST do OpenAPI com extensões Postman em JSON Para exportar e fazer download de uma API REST em definições do OpenAPI com Postman no formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Fazer download da definição da API REST do OpenAPI com integração ao API Gateway em YAML Para exportar e fazer download de uma API REST em definições do OpenAPI com integração ao API Gateway no formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Exportar API REST usando o console do API Gateway Depois de [implantar sua API REST em um estágio](set-up-deployments.md#create-deployment), você pode prosseguir e exportar essa API no estágio para um arquivo do OpenAPI usando o console do API Gateway. No painel **Estágios** no console do API Gateway, escolha **Estágios**, **Exportar**. ![\[Exportar API REST usando o console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/export-new-console.png) Especifique **Tipo de especificação da API**, **Formato** e **Extensões** para baixar a definição do OpenAPI da sua API.