Introdução à extensão do Centro de API do Azure para Visual Studio Code (visualização)
Para criar, descobrir, experimentar e consumir APIs em seu centro de APIs, você pode usar a extensão do Centro de API do Azure em seu ambiente de desenvolvimento do Visual Studio Code:
Criar APIs - Torne as APIs que você está criando detetáveis para outras pessoas registrando-as em sua central de APIs. A conformidade do design da API com deslocamento para a esquerda verifica o Visual Studio Code com suporte de revestimento integrado. Certifique-se de que as novas versões de API não quebrem os consumidores de API com a deteção de alterações de quebra.
Descobrir APIs - Navegue pelas APIs no seu centro de APIs e veja seus detalhes e documentação.
Experimente APIs - Use a interface do usuário do Swagger ou o cliente REST para explorar solicitações e respostas de API.
Consumir APIs - Gere clientes SDK de API para sua linguagem favorita, incluindo JavaScript, TypeScript, .NET, Python e Java, usando o mecanismo Microsoft Kiota que gera SDKs para Microsoft Graph, GitHub e muito mais.
Nota
A extensão do Centro de API do Azure para Visual Studio Code está em visualização. Saiba mais sobre a visualização da extensão.
Pré-requisitos
Um ou mais centros de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API.
Atualmente, você precisa receber a função de Colaborador ou permissões superiores para acessar centros de API com a extensão.
As seguintes extensões de código do Visual Studio são opcionais e necessárias apenas para determinados cenários, conforme indicado:
- Extensão de cliente REST - para enviar solicitações HTTP e exibir as respostas no Visual Studio Code diretamente
- Extensão Microsoft Kiota - para gerar clientes API
- Extensão espectral - para executar verificações de conformidade de design de API com deslocamento para a esquerda no Visual Studio Code
- CLI ótica - para detetar alterações de quebra entre documentos de especificação de API
Configurar
- Instale a extensão do Centro de API do Azure para Visual Studio Code a partir do Visual Studio Code Marketplace. Instale extensões opcionais conforme necessário.
- 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 conta do Azure com o centro de API (ou centros de API) a partir do qual você deseja exibir APIs. Também pode filtrar subscrições específicas se tiver muitas para visualizar.
Registrar APIs
Registre uma API em seu centro de API diretamente do Visual Studio Code, registrando-a como uma operação única ou com um pipeline de CI/CD.
- Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Azure API Center: Register API e pressione Enter.
- Selecione como você deseja registrar sua API com seu centro de API:
- O passo a passo é melhor para o registro único de APIs.
- O CI/CD adiciona 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.
- Conclua os passos de registo:
- Para Passo a passo, selecione o centro de API com o qual registrar APIs e responda aos prompts com informações, incluindo título, tipo, estágio do ciclo de vida, versão e especificação da API para concluir o registro da API.
- Para 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 do Azure Pipeline/GitHub Action. No push to source control, a API será registrada em seu centro de APIs.
Conformidade do projeto da API
Para garantir a conformidade do projeto 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 forro de especificação de API com o Spectral.
- 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 ativa e pressione Enter.
- 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 Remoto 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 acionará uma operação de revestimento local no Visual Studio Code. Os resultados são exibidos tanto embutidos no editor, quanto na janela Problemas (Exibir>Problemas ou Ctrl+Shift+M).
Deteção de alterações de rutura
Ao introduzir novas versões da sua API, é importante garantir que as alterações introduzidas não quebrem os consumidores de API em versões anteriores da sua API. A extensão do Centro de API do Azure para Visual Studio Code facilita isso com a deteção de alterações de quebra para documentos de especificação OpenAPI com tecnologia Optic.
- Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Azure API Center: Detect Breaking Change e pressione Enter.
- Selecione o primeiro documento de especificação da API para comparar. As opções válidas incluem especificações de API encontradas em seu centro de API, um arquivo local ou o editor ativo no Visual Studio Code.
- Selecione o segundo documento de especificação da API para comparar. As opções válidas incluem especificações de API encontradas em seu centro de API, um arquivo local ou o editor ativo no Visual Studio Code.
O Visual Studio Code abrirá uma exibição de comparação entre as duas especificações de API. Quaisquer alterações de quebra são exibidas embutidas no editor, bem como na janela Problemas (Exibir>problemas ou Ctrl+Shift+M).
Descubra APIs
Os recursos do centro de API aparecem na visualização em á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 uma Central de APIs usando o ícone de pesquisa mostrado no item de exibição em árvore da APIS .
Ver documentação da API
Você pode visualizar a documentação de uma definição de API em seu centro de API e tentar operações de API. Esse recurso só está disponível para APIs baseadas em OpenAPI em seu centro de APIs.
Expanda a visualização em árvore do Centro de API para mostrar uma definição de API.
Clique com o botão direito do mouse na definição e selecione Abrir documentação da API. Uma nova guia aparece com a interface do usuário do Swagger para a definição da API.
Para experimentar a API, selecione um ponto de extremidade, selecione Experimentar, insira os parâmetros necessários e selecione Executar.
Nota
Dependendo da API, talvez seja necessário fornecer credenciais de autorização ou uma chave de API para tentar a API.
Gerar arquivo HTTP
Você pode visualizar um .http arquivo com base na definição de API em seu centro de API. Se a extensão de cliente REST estiver instalada, você pode fazer solicitações diretório do editor de código do Visual Studio. Esse recurso só está disponível para APIs baseadas em OpenAPI em seu centro de APIs.
Expanda a visualização em árvore do Centro de API para mostrar uma definição de API.
Clique com o botão direito do mouse na definição e selecione Gerar arquivo HTTP. Aparece uma nova guia que renderiza um documento .http preenchido pela especificação da API.
Para fazer uma solicitação, selecione um ponto de extremidade e selecione Enviar solicitação.
Nota
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 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 APIs.
- Expanda a visualização em árvore do Centro de API para mostrar uma definição de API.
- Clique com o botão direito do mouse na definição e selecione Gerar cliente de API. O painel Kiota OpenAPI Generator é exibido.
- Selecione os pontos de extremidade da API e as operações HTTP que você deseja incluir em seus SDKs.
- Selecione Gerar cliente de API.
Insira os detalhes de configuração sobre o nome do SDK, namespace e diretório de saída.
Selecione o idioma para o SDK gerado.
O cliente é gerado.
Para obter detalhes sobre como usar a extensão Kiota, consulte Extensão Microsoft Kiota para Visual Studio Code.