Partilhar via

Habilite a análise de API em seu centro de API - gerenciado pela Microsoft

  • Artigo

Este artigo explica como habilitar a análise de API na Central de APIs do Azure sem precisar gerenciá-la por conta própria (visualização). A análise de API oferece recursos de revestimento para analisar definições de API no centro de API da sua organização. O Linting garante que suas definições de API sigam as regras de estilo organizacional, gerando relatórios individuais e resumidos. Use a análise de API para identificar e corrigir erros e inconsistências comuns em suas definições de API.

Nota

Com forro e análise gerenciados, o Centro de API configura um mecanismo de revestimento e quaisquer dependências e gatilhos necessários. Você também pode ativar o revestimento e a análise manualmente.

Neste cenário:

  1. Adicione um conjunto de regras de revestimento (guia de estilo da API) em sua central de API usando a extensão de código do Visual Studio para a Central de APIs do Azure.
  2. O Centro de API do Azure executa automaticamente o linting quando você adiciona ou atualiza uma definição de API. Ele também é acionado para todas as definições de API quando você implanta um conjunto de regras em sua central de APIs.
  3. Analise 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 localmente antes de implantá-lo em seu centro de API.

Limitações

  • Atualmente, apenas documentos de especificação OpenAPI em formato JSON ou YAML são analisados.
  • Por padrão, você habilita a análise com o spectral:oas conjunto de regras. Para saber mais sobre as regras internas, consulte o repositório Spectral GitHub.
  • Atualmente, você configura um único conjunto de regras e ele é aplicado a todas as definições de OpenAPI em seu centro de API.

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 revestimento 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 do Centro de API do Azure na Barra de Atividades.

  3. No painel Central de APIs, expanda o recurso da Central de APIs no qual habilitar a análise de API.

  4. Clique com o botão direito do mouse em Regras e selecione Ativar análise de API.

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

Uma mensagem notifica você depois que a análise da API é habilitada com êxito. Uma pasta para o centro de API é criada no .api-center-rules, na raiz da pasta de trabalho. A pasta do seu centro de API contém:

  • Um ruleset.yml arquivo que define o guia de estilo de API padrão usado pelo mecanismo de alinhamento.
  • Uma functions pasta com um exemplo de função personalizada que você pode usar para estender o conjunto de regras.

Com a análise habilitada, o mecanismo de revestimento analisa as definições de API em seu 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 da API configurado.

Para visualizar um resumo de análise no seu centro de API:

  1. No portal, navegue até o centro de APIs.

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

    Captura de tela do resumo da análise da 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.

    Gorjeta

    Você também pode exibir o relatório de análise da API selecionando Análise na barra de menus da definição da API.

Personalizar conjunto de regras

Você pode personalizar o conjunto de regras padrão ou substituí-lo como o guia de estilo da 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 .api-center-rules pasta na raiz da sua pasta de trabalho.
  2. Na pasta do recurso do centro de API, abra o ruleset.yml arquivo.
  3. Modifique ou substitua o conteúdo conforme necessário.
  4. Salve suas alterações em ruleset.yml.

Conjunto de regras de teste localmente

Antes de implantar o conjunto de regras personalizado em seu centro de APIs, valide-o localmente. A extensão do Centro de API do Azure para Visual Studio Code fornece suporte integrado para forro de especificação de API com Spectral.

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

  2. Digite Central de API do Azure: defina o Guia de Estilo da API ativa e pressione Enter.

  3. Escolha Selecionar arquivo local e especifique o ruleset.yml arquivo que você personalizou. Pressione Enter.

    Esta etapa torna o conjunto de regras personalizado o guia de estilo da API ativa para forro.

Agora, quando você abre um arquivo de definição de API baseado em OpenAPI, uma operação de revestimento local é acionada automaticamente no Visual Studio Code. Os resultados são exibidos em linha no editor e na janela Problemas (Ver > Problemas ou Ctrl+Shift+M).

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

Analise os resultados do forro. Faça os ajustes necessários no conjunto de regras e continue a testá-lo localmente até que ele seja executado da maneira desejada.

Implantar o conjunto de regras no seu centro de API

Para implantar o conjunto de regras personalizado em seu centro de API:

  1. No Visual Studio Code, selecione o ícone da Central de API do Azure na Barra de atividades.
  2. No painel 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 na Central de APIs.

Uma mensagem notifica você depois que as regras são implantadas com êxito no seu centro de API. O mecanismo de revestimento usa o conjunto de regras atualizado para analisar definições de API.

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

Conteúdos relacionados