Criar e registrar APIs com a extensão do Centro de API do Azure para Visual Studio Code
Os desenvolvedores de API em sua organização podem criar e registrar APIs em seu inventário do centro de API usando a extensão do Centro de API do Azure para Visual Studio Code. Os desenvolvedores de API podem:
- Adicione uma API existente a um centro de API como uma operação única ou integre um pipeline de desenvolvimento para registrar APIs como parte de um fluxo de trabalho de CI/CD.
- Use o GitHub Copilot para gerar novas especificações OpenAPI a partir do código da API.
- Use prompts de linguagem natural com o plug-in do Centro de API para o GitHub Copilot for Azure para criar novas especificações OpenAPI.
Os 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 da API.
Pré-requisitos
Um ou mais centros de API na sua subscrição do Azure.
- Atualmente, você precisa receber a função de Colaborador ou permissões superiores para gerenciar APIs com a extensão.
As seguintes extensões de código do Visual Studio são necessárias para os cenários especificados:
- Ações do GitHub - para registrar APIs usando um pipeline de CI/CD com as Ações do GitHub
- Azure Pipelines - para registrar APIs usando um pipeline de CI/CD com o Azure Pipelines
- GitHub Copilot - para gerar arquivos de especificação OpenAPI a partir do código da API
- GitHub Copilot for Azure - para gerar arquivos de especificação OpenAPI usando o plug-in do Centro de API do Azure para o GitHub Copilot para Azure
Configurar
Instale a extensão do Centro de API do Azure para Visual Studio Code a partir do Visual Studio Code Marketplace. Instale outras extensões conforme necessário.
Nota
Quando observado, determinados recursos estão disponíveis somente na versão de pré-lançamento da extensão do 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 de 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 visualização Extensões.
No Visual Studio Code, na barra de atividades à esquerda, selecione Central de APIs.
Se não tiver sessão iniciada na sua conta do Azure, selecione Iniciar sessão no Azure..., e siga as instruções para iniciar sessão. Selecione uma assinatura do Azure com o centro de API (ou centros de API) do qual você deseja exibir APIs. Também pode filtrar subscrições específicas se tiver muitas para visualizar.
Registrar uma API - passo a passo
As etapas a seguir registram uma API em seu centro de API como uma operação única.
- Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Azure API Center: Register API e pressione Enter.
- Selecione Manual.
- Selecione o centro de API com o qual registrar APIs.
- Responda prompts com informações, incluindo 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 seu inventário do centro de APIs.
Registrar APIs - pipeline de CI/CD
As etapas a seguir registram uma API em seu centro de API com um pipeline de CI/CD. Com essa opção, adicione um pipeline pré-configurado do GitHub ou do Azure DevOps ao seu espaço de trabalho 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 da API, incluindo especificação e versão, permaneçam atualizados em seu centro de API à medida que a API continua a evoluir ao longo do tempo.
- Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Azure API Center: Register API e pressione Enter.
- Selecione CI/CD.
- Selecione GitHub ou Azure DevOps, dependendo do seu mecanismo de controle de origem preferido. Um espaço de trabalho do Visual Studio Code deve estar aberto para a extensão do Centro de API do Azure para adicionar um pipeline ao seu espaço de trabalho. Depois que o arquivo for adicionado, conclua as etapas documentadas no próprio arquivo de pipeline de CI/CD para configurar as variáveis de ambiente e a identidade necessárias. No push para o controle do código-fonte, a API é registrada em seu centro de API.
Saiba mais sobre como configurar um fluxo de trabalho de Ações do GitHub para registrar APIs com sua central de APIs.
Gerar especificações OpenAPI a partir do 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 a partir do seu código de API. Clique com o botão direito do mouse no código da API, selecione Copilot nas opções e selecione Gerar documentação da API. O GitHub Copilot cria um arquivo de especificação OpenAPI.
Nota
Esse recurso está disponível na versão de pré-lançamento da extensão do Centro de APIs.
Depois de gerar o arquivo de especificação OpenAPI e verificar a precisão, você pode registrar a API com seu centro de API usando o comando Centro de API do Azure: Registrar API .
Gerar especificações OpenAPI usando prompts de linguagem natural
O plug-in do Centro de API para o GitHub Copilot para Azure ajuda você a projetar novas APIs a partir de prompts de linguagem natural. Com a assistência de IA, gere rapidamente uma especificação OpenAPI para desenvolvimento de API que esteja em conformidade com os padrões da sua organização.
Nota
Esse recurso está disponível na versão de pré-lançamento da extensão do Centro de APIs.
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 Central de API do Azure: defina o Guia de Estilo da API, faça uma seleção e pressione Enter.
Se nenhum guia de estilo for definido, o conjunto de regras padrão
spectral:oasserá usado.No painel de chat, faça uma solicitação em linguagem natural ao
@azureagente 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.
Analise a saída gerada para verificar a precisão e a conformidade com o guia de estilo da API. Refine o prompt, se necessário, para regenerar.
Gorjeta
Os prompts eficazes se concentram nos requisitos de negócios de uma API, em vez de nos detalhes da implementação. Prompts mais curtos às vezes funcionam melhor do que os mais longos.
Quando atender aos seus requisitos, salve a especificação OpenAPI gerada em um arquivo.
Registre a API com seu centro de APIs. Selecione o botão Registrar sua API na Central de APIs no painel de chat ou selecione Central de APIs do Azure: Registrar API na Paleta de Comandos e siga as instruções.