Como inspecionar uma definição AsyncAPI

Cole uma definição AsyncAPI em YAML ou JSON e a página lista os canais, as operações declaradas neles, as mensagens de cada canal, os servidores e a versão do documento. A leitura acontece no navegador: a definição não é enviada e nenhuma requisição sai da página.

É um apoio de leitura para um arquivo de especificação, não um cliente de broker nem um validador. Mostra o que está de fato no texto colado, inclusive o caso de uma referência de mensagem que aponta para uma definição ausente do documento.

  1. Cole a definição no campo ou pressione Carregar exemplo para um documento AsyncAPI 3.0 pequeno.
  2. Pressione Analisar localmente. As formas AsyncAPI 2.x e 3.0 são lidas, em YAML ou em JSON.
  3. Leia o relatório à direita: versão, título, servidores e uma linha por canal com suas operações e mensagens.
  4. Use Copiar para levar o relatório e Limpar para esvaziar o campo e o relatório.

O que o relatório mostra e o que deixa de fora

Como as duas versões da especificação são lidas

No AsyncAPI 3.0 as mensagens de um canal ficam em channel.messages, e cada operação da seção operations nomeia seu canal, geralmente por uma $ref. No 2.x o canal contém publish e subscribe, e cada um carrega uma mensagem. O inspetor lê as duas formas: uma linha 3.0 tira suas mensagens do mapa messages e uma linha 2.x de publish.message ou subscribe.message.

As referências de canal são resolvidas por nome com o escape de JSON Pointer aplicado, então uma referência como #/channels/user~1signed-up corresponde ao canal cuja chave é user/signed-up. Quando uma mensagem é uma referência em vez de um objeto embutido, o nome no fim da referência aparece na coluna em vez de deixá-la vazia.

O que o relatório contém

O relatório é JSON, então pode ser lido ou comparado numa revisão. Ele traz a versão declarada de asyncapi, o título e a versão de info, os nomes dos servidores e, por canal, as operações encontradas ao lado dos nomes de mensagem. No 2.x a operação vem do próprio canal e no 3.0 é associada pela referência do canal; um canal sem operação alguma é marcado como declared para que a diferença continue visível.

Abaixo do relatório ficam quatro contadores: versão da especificação, canais, operações e servidores. Em seguida a página lista o que notou — uma definição sem info.title ou sem nenhum canal — para que um documento vazio ou pela metade não pareça completo.

O que ele não faz

O inspetor nunca abre uma conexão, assina um tópico nem contata os servidores citados no documento. A palavra local no painel é literal: tudo é análise de texto com o JavaScript já carregado na página, e é por isso que a ferramenta continua funcionando sem conexão.

Também não é um linter de AsyncAPI. Ele não verifica se os bindings são válidos, se os esquemas referenciados existem ou se o documento cumpre todas as regras da especificação. Uma definição com um erro que aqui não é procurado será dada como lida com sucesso. Para a validação regra a regra use as ferramentas oficiais do AsyncAPI e trate esta página como uma leitura rápida da estrutura.

Limites que vale conhecer

O analisador aceita YAML e JSON comuns. Chaves duplicadas, âncoras e tags próprias além das usuais ficam fora do leitor leve de YAML, então um documento que dependa delas pode não ser lido como uma biblioteca completa o leria. Um colchete não fechado ou uma indentação quebrada são informados com o número da linha em vez de adivinhados.

O tamanho é processado no navegador, então uma definição muito grande custa memória e tempo na sua máquina, não num servidor. Um documento com várias centenas de canais é lido em cerca de dois segundos e a página continua respondendo porque o trabalho é uma única passagem sobre o texto analisado.

Ferramentas recentes: