Habilitar a análise de API no centro de API – Gerenciada pela Microsoft
Este artigo explica como habilitar a análise de API no Centro de API do Azure sem precisar gerenciá-la por conta própria. A análise de API oferece recursos de lint para analisar definições de API no centro de API da sua organização. O lint garante que suas definições de API aderem às regras de estilo organizacional, gerando relatórios individuais e resumidos. Use a análise de API para identificar e corrigir erros comuns e inconsistências em suas definições de API.
Importante
A análise de API gerenciada no Centro de API configura automaticamente um mecanismo de lint e as dependências necessárias. Você também pode habilitar o lint e a análise manualmente usando uma função do Azure personalizada. Desabilite qualquer função usada para lint manual antes de habilitar a análise de API gerenciada.
Neste cenário:
- Adicione um conjunto de lint (guia de estilo de API) ao centro de API usando a extensão do Visual Studio Code para o Centro de API do Azure.
- O Centro de API do Azure executa automaticamente o lint quando você adiciona ou atualiza uma definição de API. Ele também é disparado para todas as definições de API quando você implanta um conjunto de regras no centro de API.
- Examine os relatórios de análise de API no portal do Azure para ver como suas definições de API estão em conformidade com o guia de estilo.
- Opcionalmente, personalize o conjunto de regras para as APIs da sua organização. Teste o conjunto de regras personalizado antes de implantá-las no centro de API.
Limitações
- Atualmente, somente documentos de especificação OpenAPI no formato JSON ou YAML são analisados.
- Por padrão, você habilita a análise com o conjunto de regras
spectral:oas. Para saber mais sobre as regras internas, consulte o Repositório do Spectral no GitHub. - Atualmente, você configura um único conjunto de regras e ele é aplicado a todas as definições de OpenAPI no centro de API.
- Veja a seguir os limites para o número máximo de definições de API linted para cada quatro horas:
- Camada gratuita: 10
- Camada Standard: 100
Pré-requisitos
Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.
As seguintes extensões do Visual Studio Code:
Extensão do Centro de API do Azure para Visual Studio Code
Importante
Habilite a análise de API gerenciada usando a versão de pré-lançamento da extensão do Centro de API. Ao instalar a extensão, escolha a versão de pré-lançamento. Alterne entre versões de lançamento e pré-lançamento a qualquer momento por meio do botão Gerenciar da extensão no modo de exibição Extensões.
Habilitar a análise de API usando o Visual Studio Code
Para habilitar a análise de API usando o conjunto de regras de lint padrão:
No Visual Studio Code, abra uma pasta que você usará para gerenciar conjuntos de regras para o Centro de API do Azure.
Selecione o ícone Centro de API do Azure na barra de atividades.
No painel do Centro de API, expanda o recurso do centro de API no qual habilitar a análise de API.
Clique com o botão direito do mouse em Regras e selecione Habilitar a Análise de API.
Você recebe uma mensagem depois que a análise de API é habilitada com êxito. Uma pasta para o centro de API é criada em .api-center-rules, na raiz da pasta de trabalho. A pasta para o centro de API contém:
- Um arquivo
ruleset.ymlque define o guia de estilo de API padrão usado pelo mecanismo de lint. - Uma pasta
functionscom uma função personalizada de exemplo que você pode usar para estender o conjunto de regras.
Com a análise habilitada, o mecanismo de lint analisa as definições de API no centro de API com base no conjunto de regras padrão e gera relatórios de análise de API.
Exibir relatórios de análise de API
Exiba um resumo de análise e os relatórios de análise para suas definições de API no portal do Azure. Depois que as definições de API são analisadas, os relatórios listam erros, avisos e informações com base no guia de estilo de API configurado.
Para exibir um resumo de análise no centro de API:
No portal, navegue até seu centro de API.
No menu à esquerda, em Governança, selecione Análise de API. O resumo é exibido.
Opcionalmente, selecione o ícone Relatório de análise de API para uma definição de API. O relatório de análise de API da definição é exibido, conforme mostrado na captura de tela a seguir.
Dica
Você também pode exibir o relatório de análise de API selecionando Análise na barra de menus da definição de API.
Personalizar o conjunto de regras
Você pode personalizar o conjunto de regras padrão ou substituí-lo como o guia de estilo de API da sua organização. Por exemplo, você pode estender o conjunto de regras ou adicionar funções personalizadas.
Para personalizar ou substituir o conjunto de regras:
- No Visual Studio Code, abra a pasta
.api-center-rulesna raiz da pasta de trabalho. - Na pasta do recurso do centro de API, abra o arquivo
ruleset.yml. - Modifique ou substitua o conteúdo conforme necessário.
- Salve as alterações em
ruleset.yml.
Testar o conjunto de regras localmente
Antes de implantar o conjunto de regras personalizado no centro de API, valide-o localmente. 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.
No Visual Studio Code, 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.
Escolha Selecionar arquivo local e especifique o arquivo
ruleset.ymlpersonalizado. Pressione Enter.Esta etapa torna o conjunto de regras personalizado o guia de estilo de API ativo para lint.
Agora, quando você abra um arquivo de definição de API baseado em OpenAPI, uma operação de lint local é disparada automaticamente no Visual Studio Code. Os resultados são exibidos em linha no editor e na janela Problemas (Exibir > Problemas ou Ctrl+Shift+M).
Examine os resultados de lint. Faça os ajustes necessários ao conjunto de regras e continue testando-o localmente até que ele seja executado como você deseja.
Implantar o conjunto de regras no centro de API
Para implantar o conjunto de regras personalizar no centro de API:
- No Visual Studio Code, selecione o ícone Centro de API do Azure na barra de atividades.
- No painel do Centro de API, expanda o recurso do centro de API no qual você personalizou o conjunto de regras.
- Clique com o botão direito do mouse em Regras e selecione Implantar regras no Centro de API.
Você recebe uma mensagem depois que as regras são implantadas com êxito no centro de API. O mecanismo de lint usa o conjunto de regras atualizado para analisar definições de API.
Para ver os resultados do lint com o conjunto de regras atualizado, exiba os relatórios de análise de API no portal.