Analisar APIs no centro de API - Gerenciado pela Microsoft

O Centro de APIs da sua organização inclui recursos de verificação gerenciados pela Microsoft (versão preliminar) para analisar definições de API quanto à conformidade com as regras de estilo da organização, gerando relatórios individuais e resumidos. A análise de API identifica e ajuda a corrigir erros e inconsistências comuns nas definições de API.

Utilizando a análise de API:

• O Centro de API do Azure analisa automaticamente as definições de API sempre que você adiciona ou atualiza uma definição de API. O linting das suas definições de API é feito por padrão com um spectral:oas conjunto de regras (guia de estilo de API).
• Relatórios de análise de API são gerados no portal do Azure, mostrando como as definições de API estão em conformidade com o guia de estilo.
• Use perfis de análise para especificar o conjunto de regras e as condições de filtro para as APIs analisadas. Personalize o conjunto de regras de um perfil usando a extensão do Centro de API Azure para Visual Studio Code.

Limitações

• Atualmente, somente documentos de especificação OpenAPI e AsyncAPI nos formatos JSON ou YAML são analisados.
• Há limites para o número de perfis de análise e o número máximo de definições de API analisadas. A análise pode levar de alguns minutos a 24 horas para ser concluída.

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você ainda não tiver um, consulte Início Rápido: Criar seu centro de API.
• Para personalizar o conjunto de regras, utilize o Visual Studio Code e as seguintes extensões do Visual Studio Code:
  • Extensão do Centro de API do Azure para Visual Studio Code
  • Extensão Spectral para Visual Studio Code

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.

No relatório de análise de API, revise também o conjunto de regras usado para a análise e o histórico de verificações.

Para exibir um resumo de análise no centro de API:

1. No portal, navegue até seu centro de API.

2. No menu à esquerda, em Governança, selecione Análise de API. O resumo é exibido.

   

3. 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.

Gerenciar perfis de análise

O Centro de APIs do Azure usa perfis de análise para verificar e analisar APIs. Um perfil de análise especifica um conjunto de regras e, opcionalmente, filtra as condições para APIs analisadas. O perfil de análise padrão aplica o spectral:oas conjunto de regras a todas as definições OpenAPI e AsyncAPI.

Você pode personalizar o conjunto de regras e definir condições de filtro no perfil padrão ou criar um novo perfil. Por exemplo, talvez você queira usar um perfil para APIs que estão em desenvolvimento e um diferente para APIs que estão em produção.

Para criar um perfil de análise:

1. No portal do Azure, navegue até o centro de API.
2. No menu à esquerda, em Governança, selecione Análise de API>Gerenciar perfis de análise>+ Criar perfil de análise.
3. No painel Criar novo perfil de análise , insira um nome e uma descrição para o perfil.
4. Em Conjunto de regras, o tipo de analisador (mecanismo de linting) para o conjunto de regras é exibido. Atualmente, há suporte apenas para o Spectral.
5. Em Definir condições de filtro, adicione uma ou mais condições de filtro para definições de API às quais o perfil é aplicado.
6. Selecione Criar.

O perfil é criado e um modelo de conjunto de regras é gerado. Para exibir o conjunto de regras atual, selecione o perfil e, no menu de contexto (...), selecione Exibir o conjunto de regras.

Para personalizar o conjunto de regras, prossiga para as seções a seguir.

Personalizar o conjunto de regras do perfil

Use a extensão Visual Studio Code para Azure Centro de API para personalizar o conjunto de regras de um perfil. Depois de personalizar o conjunto de regras e testá-lo localmente, você pode implantá-lo de volta no centro de API.

1. No Visual Studio Code, selecione o ícone Centro de API do Azure na barra de atividades.
2. No painel Centro de API, expanda o recurso do centro de API com o qual você está trabalhando e expanda Perfis.
3. Expanda o perfil que você deseja modificar e selecione ruleset.yaml.
4. Modifique ou substitua o conteúdo conforme necessário.
5. Salve as alterações em ruleset.yaml.

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 oferece suporte integrado para linting de especificações de API com o Spectral.

1. No Visual Studio Code, use o atalho de teclado Ctrl+Shift+P para abrir a paleta de comandos.

2. Digite Centro de API do Azure: definir o Guia de Estilo de API ativo e pressione Enter.

3. Escolha Selecionar arquivo local e especifique o arquivo ruleset.yaml personalizado. Pressione Enter.

   Esta etapa torna o conjunto de regras personalizado o guia de estilo de API ativo para linting local.

Agora, quando você abre 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).

Revise os resultados do linting. 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 personalizado na Central de API:

1. No Visual Studio Code, selecione o ícone Centro de API do Azure na barra de atividades.
2. No painel do Centro de API, expanda o recurso do centro de API no qual você personalizou o conjunto de regras.
3. Expanda perfis.
4. Clique com o botão direito do mouse no perfil no qual você personalizou o conjunto de 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 linting usa o conjunto de regras atualizado para analisar as definições de API no perfil.

Para ver os resultados do linting com o conjunto de regras atualizado, visualize os relatórios de análise de API no portal.

Conteúdo relacionado

• Para saber mais sobre o conjunto de regras padrão interno, consulte o repositório Spectral no GitHub.
• Habilitar a análise de API no centro de API – autogerenciada