Habilitar a análise de API no centro de API – Gerenciada pela Microsoft

  • Artigo

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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 regrasspectral: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

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:

  1. No Visual Studio Code, abra uma pasta que você usará para gerenciar conjuntos de regras para o Centro de API do Azure.

  2. Selecione o ícone Centro de API do Azure na barra de atividades.

  3. No painel do Centro de API, expanda o recurso do centro de API no qual habilitar a análise de API.

  4. Clique com o botão direito do mouse em Regras e selecione Habilitar a Análise de API.

    Captura de tela de habilitação da análise e lint da API no Visual Studio Code.

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.yml que define o guia de estilo de API padrão usado pelo mecanismo de lint.
  • Uma pasta functions com 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:

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

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

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