Importar uma especificação de OpenAPI

2025-05-20

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo mostra como importar uma API de back-end de “Especificação de OpenAPI” para o Gerenciamento de API do Azure usando várias ferramentas. O artigo também mostra como testar a API do Gerenciamento de API.

Neste artigo, você aprenderá como:

Importar uma especificação de OpenAPI usando o portal do Azure, a CLI do Azure ou o Azure PowerShell
Testar a API no Portal do Azure

Observação

As limitações de importação de API estão documentadas em restrições de importação de API e problemas conhecidos.

Pré-requisitos

Uma instância de Gerenciamento de API. Se você ainda não tem uma, conclua o seguinte guia de início rápido: Criar uma instância de Gerenciamento de API do Azure.
CLI do Azure
- Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao Azure Cloud Shell.
- Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
  - Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
  - Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar e gerenciar extensões com a CLI do Azure.
  - Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
PowerShell do Azure
- Se você optar por usar o Azure PowerShell localmente:
  - Instale a versão mais recente do módulo do Az PowerShell.
  - Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
- Se você optar por usar o Azure Cloud Shell:
  - Confira Visão geral do Azure Cloud Shell para obter mais informações.

Importar uma API de back-end

Para este exemplo, você importa a Especificação de OpenAPI para a API Petstore de código aberto, mas pode substituir uma especificação de OpenAPI de sua escolha.

No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu à esquerda, selecione APIs >+Adicionar API.
Em Criar com base na definição, selecione OpenAPI.
Insira as configurações de API. Você pode definir os valores durante a criação ou configurá-los mais tarde, acessando a guia Configurações. As configurações são explicadas no tutorial Importar e publicar sua primeira API.
Selecione Criar.

O exemplo a seguir usa o comando az apim api import para importar uma especificação de API da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro --specification-path.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Depois de importar a API, se necessário, você pode atualizar as configurações usando o comando az apim api update.

O exemplo a seguir usa o comando Import-AzApiManagementApi do cmdlet do Azure PowerShell para importar uma especificação de OpenAPI da URL especificada para uma instância de Gerenciamento de API chamada apim-hello-world. Para importar usando um caminho para uma especificação em vez de uma URL, use o parâmetro -SpecificationPath.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Depois de importar a API, se necessário, você pode atualizar as configurações usando o cmdlet Set-AzApiManagementApi.

Exibir e editar especificação de OpenAPI

No portal, use o editor de especificação de OpenAPI para exibir, validar ou editar a especificação da API importada.

Para usar o editor de especificação de OpenAPI:

No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu do lado esquerdo, em APIs, selecione APIs><sua API>>Todas as operações.
Na guia Design, em Front-end, selecione Editor de especificação de OpenAPI (ícone de lápis). Você pode abrir a especificação no formato JSON ou YAML.
Examine ou edite a especificação conforme necessário. Salve suas alterações.

Validar em relação a um esquema de especificação de OpenAPI

Você pode configurar as políticas de validação do Gerenciamento de API para validar solicitações e respostas (ou respectivos elementos) em relação ao esquema em uma especificação OpenAPI. Por exemplo, use a política validate-content para validar o tamanho ou o conteúdo de uma solicitação ou corpo de resposta.

Testar a nova API no portal

As operações podem ser chamadas diretamente do portal, que fornece uma maneira conveniente para administradores exibirem e testarem as operações de uma API.

Selecione a API que você criou na etapa anterior.
Selecione a guia Testar.
Selecione uma operação. A página exibe os campos dos parâmetros de consulta e os campos dos cabeçalhos.

Observação

No console de teste, o Gerenciamento de API preenche automaticamente um cabeçalho Ocp-Apim-Subscription-Key e configura a chave de assinatura da assinatura interna de acesso total. Essa chave permite o acesso a todas as API na instância de Gerenciamento de API. Opcionalmente, exiba o cabeçalho Ocp-Apim-Subscription-Key selecionando o ícone "olho" ao lado da Solicitação HTTP.
Dependendo da operação, insira valores de parâmetro de consulta, valores de cabeçalho ou um corpo da solicitação. Selecione Enviar.

Quando o teste é bem-sucedido, o back-end responde com um código de resposta HTTP bem-sucedido e alguns dados.

Dica

Por padrão, o console de teste envia uma solicitação para o proxy CORS do Gerenciamento de API, que encaminha a solicitação para a instância Gerenciamento de API, que a encaminha para o back-end. Esse proxy usa o endereço de IP público 13.91.254.72 e só pode alcançar pontos de extremidade públicos. Se você quiser enviar uma solicitação diretamente do navegador para o serviço Gerenciamento de API, selecione Ignorar proxy CORS. Use essa opção quando quiser usar o console de teste e o gateway do Gerenciamento de API estiver isolado na rede ou não permitir o tráfego do proxy CORS.

Para depurar uma API, confira o Tutorial: Depurar suas APIs usando o rastreamento de solicitações.

Acrescentar outras APIs

Você pode compor uma API a partir de APIs que são disponibilizadas por diferentes serviços, incluindo:

Uma especificação do OpenAPI
Uma API SOAP
Uma API da GraphQL
Um aplicativo Web hospedado no Serviço de Aplicativo do Azure
Funções do Azure
Aplicativos Lógicos do Azure
Azure Service Fabric

Observação

Quando você importa uma API, as operações são acrescentadas à API atual.

Para acrescentar uma API a uma API existente:

Acesse sua instância de Gerenciamento de API do Azure no portal do Azure:
Selecione APIs na página Visão geral ou selecione APIs APIs> no menu à esquerda.
Selecione as reticências (...) próximas à API na qual deseja acrescentar outra API.
Selecione Importar no menu suspenso:
Selecione um serviço de onde será importada a API.

Compartilhar via