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

Os desenvolvedores de API da sua organização podem criar e registrar APIs no seu inventário de centro de APIs, usando a extensão Centro de APIs do Azure para o Visual Studio Code. Desenvolvedores de API podem:

• Adicionar uma API existente a um centro de APIs como uma operação única ou integrar um pipeline de desenvolvimento para registrar APIs como parte de um fluxo de trabalho CI/CD.
• Use o GitHub Copilot para gerar novas especificações OpenAPI do código de API.
• Use prompts de linguagem natural com o plug-in do Centro de API para GitHub Copilot para Azure para criar especificações de OpenAPI.

Desenvolvedores de API também podem aproveitar os recursos da extensão para descobrir e consumir APIs no centro de APIs e garantir a governança de APIs.

Pré-requisitos

• Um ou mais centros de API em sua assinatura do Azure.

  • Atualmente, você precisa receber a função Colaborador de Serviço do Centro de API do Azure ou permissões mais altas em um centro de API para gerenciar APIs com a extensão.

• Visual Studio Code

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

As seguintes extensões do Visual Studio Code são necessárias para os cenários especificados:

• GitHub Actions - para registrar APIs usando um pipeline CI/CD com o GitHub Actions
• Azure Pipelines - para registrar APIs usando um pipeline CI/CD com o Azure Pipelines
• GitHub Copilot - para gerar arquivos de especificação OpenAPI do código da API
• GitHub Copilot para Azure – para gerar arquivos de especificação de OpenAPI usando o Plug-in do Centro de API do Azure para GitHub Copilot para Azure

Instalação

1. Instale a extensão do Centro de API do Azure para Visual Studio Code no Marketplace do Visual Studio Code. Instale outras extensões conforme necessário.

   Observação

   Onde indicado, certos recursos estão disponíveis apenas na versão prévia da extensão Centro de API do Azure. 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.

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 assinatura do Azure com o centro de APIs (ou centros de APIs) dos quais você deseja exibir as APIs. Você também pode filtrar em assinaturas específicas se tiver muitos para exibir.

Registrar uma API - etapa por etapa

As etapas a seguir registram uma API no seu centro de APIs como uma operação única.

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 Manual.
3. Selecione o centro de APIs para registrar APIs.
4. Responda aos prompts com informações, incluindo o título da API, tipo, título da versão, ciclo de vida da versão, título da definição, nome da especificação e arquivo de definição para concluir o registro da API.

A API é adicionada ao inventário do seu centro de APIs.

Registrar APIs - pipeline CI/CD

As etapas a seguir registram uma API no seu centro de APIs com um pipeline CI/CD. Com esta opção, adicione um pipeline pré-configurado do GitHub ou Azure DevOps ao seu workspace ativo do Visual Studio Code, que será executado como parte de um fluxo de trabalho CI/CD em cada commit ao 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.

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 CI/CD.
3. Selecione GitHub ou Azure DevOps, dependendo do seu 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. Após o arquivo ser adicionado, conclua as etapas documentadas no próprio arquivo do pipeline CI/CD para configurar as variáveis de ambiente e identidade necessárias. No push para o controle do código-fonte, a API é registrada no seu centro de APIs.

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

Gerar especificação de OpenAPI com base no 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. O GitHub Copilot cria um arquivo de especificação OpenAPI.

Observação

Esse recurso está disponível na versão de pré-lançamento da extensão do API Center.

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.

Gerar especificação OpenAPI usando prompts de linguagem natural

O plug-in do Centro de API do GitHub Copilot para Azure ajuda você a criar APIs a partir de prompts de linguagem natural. Com a assistência de IA, gere rapidamente uma especificação de OpenAPI para desenvolvimento de API que esteja em conformidade com os padrões da sua organização.

Observação

Esse recurso está disponível na versão de pré-lançamento da extensão do API Center.

1. Se desejar, defina um guia de estilo de API ativo. 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, faça uma seleção e pressione Enter.

   Se nenhum guia de estilo for definido, o conjunto de regras padrão spectral:oas será usado.

2. No painel de chat, faça uma solicitação em linguagem natural ao agente @azure para descrever o que a API faz. Exemplo:

   @azure Generate OpenAPI spec: An API that allows customers to pay for an order using various payment methods such as cash, checks, credit cards, and debit cards.
   

   O agente responde com um documento de especificação OpenAPI.

   

3. Examine a saída gerada para obter precisão e conformidade com o seu guia de estilo de API. Refinar o prompt, se necessário, para regenerar.

   Dica

   Os prompts efetivos se concentram nos requisitos de negócios de uma API em vez de nos detalhes de implementação. Prompts mais curtos às vezes funcionam melhor do que os mais longos.

4. Quando ele atender aos seus requisitos, salve a especificação de OpenAPI gerada em um arquivo.

5. Registre a API no centro de API. Selecione o botão Registrar sua API no Centro de API no painel de chat ou selecione Centro de API do Azure: registrar a API na Paleta de Comandos e siga os prompts.

Conteúdo relacionado

• Centro de API do Azure – principais conceitos
• Descubra e consuma APIs com a extensão Centro de APIs do Azure para Visual Studio Code
• Governe APIs com a extensão Centro de API do Azure para Visual Studio Code
• Habilitar e visualizar o catálogo de API da plataforma no Visual Studio Code