Criar e registrar APIs com a extensão do Centro de API do Azure para Visual Studio Code

Para criar, descobrir, explorar e consumir APIs em seu centro de API, você pode usar a extensão do Centro de API do Azure em seu ambiente de desenvolvimento do Visual Studio Code. A extensão oferece os seguintes recursos para desenvolvedores de API:

• Criar APIs – tornar as APIs que você está criando detectáveis para outras pessoas registrando-as diretamente no centro de API ou usando pipelines de CI/CD no GitHub ou no Azure DevOps. Adote a abordagem shift-left para as verificações de conformidade de design de API no Visual Studio Code com suporte integrado de lint. Verifique se as novas versões de API não interrompem os consumidores de API com a detecção de alterações interruptivas.

• Descobrir APIs – Procurar as APIs em seu centro de API e exibir seus detalhes e documentação.

• Explorar APIs – Usar a interface do usuário do Swagger ou o cliente REST para explorar solicitações e respostas de API.

• Consumir APIs – Gerar clientes do SDK de API para seu idioma favorito, incluindo JavaScript, TypeScript, .NET, Python e Java, usando o mecanismo Microsoft Kiota que gera SDKs para Microsoft Graph, GitHub e muito mais.

Pré-requisitos

• Um ou mais centros de API em sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.

  Atualmente, você precisa receber a função Colaborador ou permissões mais altas para gerenciar centros de API com a extensão.

• Visual Studio Code

• Extensão do Centro de API do Azure para Visual Studio Code

  Observação

  Quando especificado, certos recursos estão disponíveis apenas na versão pré-lançamento da extensão. Ao instalar a extensão do Visual Studio Code Marketplace, você pode optar por instalar a versão de lançamento ou uma versão pré-lançamento. Alterne entre as duas versões a qualquer momento usando o menu de contexto do botão Gerenciar da extensão na exibição de Extensões.

As seguintes extensões do Visual Studio Code são opcionais e necessárias apenas para determinados cenários, conforme indicado:

• Extensão do cliente REST – para enviar solicitações HTTP e exibir as respostas diretamente no Visual Studio Code
• Extensão do Microsoft Kiota – para gerar clientes de API
• Extensão espectral: para executar verificações de conformidade antecipadas do tipo Shift Left do design de API no Visual Studio Code
• CLI do Optic – Para detectar alterações interruptivas entre os documentos de especificação da API
• GitHub Copilot - para gerar arquivos de especificação OpenAPI do código da API

Instalação

1. Instale a extensão do Centro de API do Azure para Visual Studio Code no Marketplace do Visual Studio Code. Instale extensões opcionais conforme necessário.
2. No Visual Studio Code, na Barra de Atividades à esquerda, selecione Centro de API.
3. Se você não estiver conectado à sua conta do Azure, selecione Entrar no Azure... e siga os prompts para entrar. Selecione uma conta do Azure com o centro de API (ou centros de API) da qual você deseja exibir AS APIs. Você também pode filtrar em assinaturas específicas se tiver muitos para exibir.

Registrar APIs

Registre uma API no centro de API diretamente do Visual Studio Code, registrando-a como uma operação única ou com um pipeline de CI/CD.

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: registrar API e pressione Enter.

2. Selecione como você deseja registrar sua API no centro de API:

   • Passo a passo é melhor para o registro único de APIs.
   • O CI/CD adiciona um pipeline do GitHub ou do Azure DevOps pré-configurado ao workspace ativo do Visual Studio Code que é executado como parte de um fluxo de trabalho de CI/CD em cada confirmação para o controle do código-fonte. É recomendável inventariar APIs com seu centro de API usando CI/CD para garantir que os metadados de API, incluindo especificação e versão, permaneçam atualizados no centro de API à medida que a API continua evoluindo ao longo do tempo.

3. Conclua as etapas de registro:

   • Para passo a passo, selecione o centro de API com o qual registrar APIs e responda aos prompts com informações, incluindo título da API, tipo, estágio do ciclo de vida, versão e especificação para concluir o registro de API.
   • Para CI/CD, selecione GitHub ou Azure DevOps, dependendo do mecanismo de controle do código-fonte preferido. Um workspace do Visual Studio Code deve estar aberto para que a extensão do Centro de API do Azure adicione um pipeline ao seu workspace. Depois que o arquivo for adicionado, conclua as etapas documentadas no próprio arquivo de pipeline de CI/CD para configurar a identidade e as variáveis de ambiente do Azure Pipeline/GitHub Action. Ao enviar por push para o controle do código-fonte, a API será registrada no centro de API.

   Saiba mais sobre como configurar um fluxo de trabalho do GitHub Actions para registrar APIs no centro de API.

Conformidade de design de API

Para garantir a conformidade do design com os padrões organizacionais à medida que você cria APIs, a extensão do Centro de API do Azure para Visual Studio Code fornece suporte integrado para lint de especificação de API com o Spectral.

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: definir o Guia de Estilo de API ativo e pressione Enter.
2. Selecione uma das regras padrão fornecidas ou, se sua organização tiver um guia de estilo já disponível, use Selecionar Arquivo Local ou URL Remota de Entrada para especificar o conjunto de regras ativo no Visual Studio Code. Pressione Enter.

Depois que um guia de estilo de API ativo for definido, abrir qualquer arquivo de especificação baseado em OpenAPI ou AsyncAPI disparará uma operação de lint local no Visual Studio Code. Os resultados são exibidos embutidos no editor, bem como na janela Problemas (Exibir>Problemas ou Ctrl+Shift+M).

Detecção de alterações interruptivas

Ao introduzir novas versões da API, é importante garantir que as alterações introduzidas não interrompam os consumidores de API nas versões anteriores dela. A extensão do Centro de API do Azure para Visual Studio Code facilita a detecção de alterações interruptivas para documentos de especificação do OpenAPI ativados pelo Optic.

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: Detectar Alteração Interruptiva e pressione ENTER.
2. Selecione o primeiro documento de especificação de API a ser comparado. As opções válidas incluem especificações de API encontradas no centro de API, em um arquivo local ou no editor ativo no Visual Studio Code.
3. Selecione o segundo documento de especificação de API a ser comparado. As opções válidas incluem especificações de API encontradas no centro de API, em um arquivo local ou no editor ativo no Visual Studio Code.

O Visual Studio Code abrirá uma exibição comparativa entre as duas especificações de API. As alterações interruptivas são exibidas embutidos no editor, bem como na janela Problemas (Exibir>Problemas ou CTRL+SHIFT+M).

Gerar o arquivo de especificação OpenAPI pelo código da API

Use o poder do GitHub Copilot com a extensão do Centro de API do Azure para Visual Studio Code para criar um arquivo de especificação OpenAPI do código da API. Clique com o botão direito no código da API, selecione Copilot nas opções e, em seguida, selecione Gerar documentação da API. Isso criará um arquivo de especificação OpenAPI.

Depois de gerar o arquivo de especificação OpenAPI e verificar a precisão, você pode registrar a API no centro de API usando o comando Centro de API do Azure: Registrar a API.

Descobrir APIs

Os recursos do centro de API aparecem no modo de exibição de árvore no lado esquerdo. Expanda um recurso do centro de API para ver APIs, versões, definições, ambientes e implantações.

Pesquise APIs em um Centro de API usando o ícone de pesquisa mostrado no item do modo de exibição de árvore Apis.

Exibir documentação da API

Você pode exibir a documentação de uma definição de API no centro de API e experimentar operações de API. Esse recurso só está disponível para APIs baseadas em OpenAPI em seu centro de API.

1. Expanda o modo de exibição de árvore do Centro de API para mostrar uma definição de API.

2. Clique com o botão direito do mouse na definição e selecione Abrir Documentação da API. Uma nova guia é exibida com a interface do usuário do Swagger para a definição de API.

   

3. Para experimentar a API, selecione um ponto de extremidade, selecione Experimentar, insira os parâmetros necessários e selecione Executar.

   Observação

   Dependendo da API, talvez seja necessário fornecer credenciais de autorização ou uma chave de API para experimentar a API.

   Dica

   Usando a versão pré-lançamento da extensão, você pode gerar documentação de API em Markdown, um formato fácil de manter e compartilhar com os usuários finais. Clique com o botão direito do mouse na definição e selecione Gerar Markdown.

Gerar arquivo HTTP

Você pode exibir um arquivo .http com base na definição de API no centro de API. Se a extensão cliente REST estiver instalada, você poderá fazer o diretório de solicitações do editor do Visual Studio Code. Esse recurso só está disponível para APIs baseadas em OpenAPI em seu centro de API.

1. Expanda o modo de exibição de árvore do Centro de API para mostrar uma definição de API.

2. Clique com o botão direito do mouse na definição e selecione Gerar Arquivo HTTP. Uma nova guia é exibida que renderiza um documento .http preenchido pela especificação da API.

   

3. Para fazer uma solicitação, selecione um ponto de extremidade e selecione Enviar Solicitação.

   Observação

   Dependendo da API, talvez seja necessário fornecer credenciais de autorização ou uma chave de API para fazer a solicitação.

Gerar cliente de API

Use a extensão do Microsoft Kiota para gerar um cliente de API para seu idioma favorito. Esse recurso só está disponível para APIs baseadas em OpenAPI em seu centro de API.

1. Expanda o modo de exibição de árvore do Centro de API para mostrar uma definição de API.
2. Clique com o botão direito do mouse na definição e selecione Gerar Cliente de API. O painel Gerador do OpenAPI Kiota é exibido.
3. Selecione os pontos de extremidade de API e as operações HTTP que você deseja incluir em seus SDKs.
4. Selecione Gerar cliente de API.

   1. Insira detalhes de configuração sobre o nome, o namespace e o diretório de saída do SDK.

   2. Selecione o idioma do SDK gerado.

      

O cliente é gerado.

Para obter detalhes sobre como usar a extensão Kiota, consulte extensão do Microsoft Kiota para Visual Studio Code.

Exportar especificações de API

Você pode exportar uma especificação de API de uma definição e depois baixá-la como um arquivo.

Para exportar uma especificação no modo de exibição de árvore da extensão:

1. Expanda o modo de exibição de árvore do Centro de API para mostrar uma definição de API.

2. Clique com o botão direito do mouse na definição e selecione exportar documento de especificação da API. Uma nova aba abrirá, exibindo o documento de especificação da API.

   

Também é possível exportar uma especificação através da Paleta de Comandos:

1. Use o atalho Ctrl+Shift+P para abrir a Paleta de Comandos.
2. Selecione Centro de API do Azure: Exportar documento de especificação da API.
3. Faça seleções para navegar até uma definição de API. Uma nova aba abrirá, exibindo o documento de especificação da API.

Conteúdo relacionado

• Centro de API do Azure – principais conceitos
• Habilitar e visualizar o catálogo de API da plataforma no Visual Studio Code