Compartilhar via

Analisar APIs no centro de API - Gerenciado pela Microsoft

  • Artigo

O centro de API da sua organização inclui recursos de lint internos, gerenciados pela Microsoft (versão prévia) para analisar definições de API quanto à aderência às regras de estilo organizacional, 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.

Com 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. As definições de API são verificadas por padrão com um conjunto de regras spectral:oas (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.
  • Você pode usar a extensão do Centro de API do Azure para Visual Studio Code para personalizar e testar seu próprio guia de estilo de API localmente e implantá-lo no centro de API.

Importante

Se preferir, você pode habilitar a análise e o lint autogerenciados usando uma função personalizada do Azure, substituindo os recursos internos. Desabilite qualquer função usada para lint autogerenciado antes de usar a análise de API gerenciada.

Limitações

  • Atualmente, somente documentos de especificação OpenAPI e AsyncAPI nos formatos JSON ou YAML são analisados.
  • Atualmente, você configura um único conjunto de regras e ele é aplicado a todas as definições de OpenAPI no centro de API.
  • Há limites para 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

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

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.

    Captura de tela do resumo da análise de API no portal.

  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.

    Captura de tela de um relatório de análise de API no portal.

    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 usar a extensão do Centro de API do Azure para Visual Studio Code para personalizar o conjunto de regras padrão do centro de API ou substituí-lo pelo 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:

  1. No Visual Studio Code, selecione o ícone Centro de API do Azure na barra de atividades.
  2. Abra a pasta .api-center-rules na raiz da pasta de trabalho.
  3. Na pasta do recurso do centro de API, abra o arquivo ruleset.yml.
  4. Modifique ou substitua o conteúdo conforme necessário.
  5. 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.

  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.yml personalizado. 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).

Dica

Os desenvolvedores de API da sua organização também podem usar esse recurso de lint local para ajudar a melhorar as definições de API antes de registrar as APIs no centro de API.

Captura de tela de lint de uma definição de API no Visual Studio Code.

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:

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

Conteúdo relacionado