OpenAPI / AsyncAPI

Adicione uma especificação OpenAPI ou AsyncAPI e obtenha uma referência de API nativa — uma página real por operação, na sua barra lateral e na busca.

Aponte o Blume para uma especificação OpenAPI e ele gera uma referência de API nativa: uma página real por operação, agrupada por tag em uma barra lateral delimitada por aba, com tabelas de esquema, exemplos de requisição/resposta, amostras de código geradas e um painel interativo Try it. Como cada operação é uma página Blume genuína, ela ganha sua própria URL, aparece na busca do site e no llms.txt, e recebe uma imagem Open Graph — igual a qualquer documento escrito à mão. A configuração abaixo aponta o Blume para a especificação pública do Petstore como exemplo.

openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}

Isso monta a referência em /reference (uma página de visão geral) com cada operação em /reference/<tag>/<operation>. O spec é uma URL http(s) ou um caminho para um arquivo local no seu projeto. O Blume o analisa com o parser OpenAPI do Scalar — especificações Swagger 2.0 e OpenAPI 3.0 são atualizadas para 3.1 automaticamente. Está documentando uma API GraphQL? Veja a referência GraphQL.

A referência não adiciona uma aba de cabeçalho por conta própria. Para exibi-la, aponte uma aba de navegação para sua rota — isso também delimita a barra lateral de operações para o renderizador nativo:

navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}

Uma especificação local

Um caminho relativo é resolvido a partir da raiz do seu projeto e lido em tempo de build. Tanto JSON quanto YAML funcionam:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}

Rota

route controla onde a referência é montada — a página de visão geral e o prefixo para cada rota de operação (e a rota para a qual você aponta uma aba de navegação):

openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}

Amostras de código e esquemas

codeSamples escolhe quais linguagens são renderizadas por operação (nativas: curl, js, python); expandSchemas inicia as linhas de esquema aninhadas expandidas em vez de recolhidas:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}

Playground Try it

Páginas de operação renderizadas nativamente vêm com um painel interativo Try it por padrão. O Blume gera o formulário a partir da própria operação: um campo por parâmetro de caminho, consulta e cabeçalho, um editor de corpo construído a partir do esquema do corpo da requisição, tudo pré-preenchido a partir dos exemplos da especificação. Um seletor de servidor lista os servers da especificação, com um campo de texto livre para qualquer outra URL base, e os campos de autenticação correspondem à segurança resolvida da operação — token bearer, chave de API e credenciais basic, com OAuth2 como um campo para colar o token (traga um token de acesso; o Blume não executa o fluxo).

O painel e as amostras de código andam em sincronia: valores digitados no formulário atualizam as amostras geradas ao vivo, então um comando curl copiado sempre corresponde exatamente ao que o Send faria. E ele fica fora do caminho — o painel é renderizado no servidor já recolhido, e seu JavaScript é carregado apenas quando um leitor o abre pela primeira vez. Leitores que nunca o tocam não baixam nada disso.

playground: false é todo o interruptor de desligamento:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}

Credenciais

As credenciais digitadas nos campos de autenticação ficam na memória e desaparecem ao recarregar. Marcar Remember on this device as persiste no localStorage, delimitado à origem da documentação — elas nunca são enviadas para lugar nenhum além da API que está sendo chamada. As amostras de código continuam exibindo espaços reservados (YOUR_TOKEN e companhia) independentemente do que for digitado, a menos que o leitor ative Include my values in samples.

CORS e o proxy

Assim como no renderizador Scalar, as requisições vão diretamente do navegador para a API de destino, então a API precisa permitir requisições de origem cruzada a partir do site de documentação (Access-Control-Allow-Origin). Para APIs que não podem, defina playground.proxy: uma URL roteia as requisições através de um proxy hospedado por você, e true habilita a rota interna /_api-proxy — que precisa de um build de servidor, então exige deployment.output: "server":

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}

O proxy interno só encaminha requisições para as origens que suas especificações declaram em servers — inclusive através de redirecionamentos — então uma implantação pública de documentação não pode ser apontada para outros hosts na sua rede. Uma Custom base URL digitada no painel não é um servidor documentado: com o proxy habilitado, requisições para ela são recusadas com um 403.

Múltiplas especificações

Use sources para publicar mais de uma especificação. Cada fonte recebe sua própria rota de visão geral, páginas de operação e aba de cabeçalho. Dê a cada uma um label (usado para a aba e para derivar sua rota), ou defina uma route explícita:

openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}

spec é um atalho para um sources de entrada única, então você só recorre a sources quando tem mais de uma.

Indexação por fonte

As páginas geradas participam da busca, do llms.txt e da indexação por rastreadores por padrão. Uma especificação secundária ou sobreposta pode optar por sair de qualquer superfície sem ocultar suas páginas ou removê-la da navegação:

openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}

• includeInSearch: false mantém a visão geral e as operações da fonte fora da busca do site.
• includeInLlms: false as mantém fora de ambos os arquivos llms.txt.
• noindex: true adiciona metadados noindex para rastreadores e remove as páginas do sitemap.

A meta descrição de cada página de operação é a própria description da operação (ou o summary), seguida de uma frase gerada que nomeia o endpoint — “Reference for the GET /pets endpoint in the Petstore API.” — então uma especificação com resumos secos de uma linha ainda entrega uma descrição distinta e do tamanho de um snippet por página. Essa frase está em inglês. Em um site cuja prosa da especificação está escrita em outro idioma, defina seoDescriptionSuffix: false na fonte para descartá-la e descrever cada página apenas com a prosa autoral; uma operação sem description nem summary recorre ao seu título (GET /pets), então nenhuma página é entregue com uma descrição vazia:

openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}

Com o renderizador Scalar, apenas noindex se aplica — uma referência renderizada pelo Scalar já fica fora da busca e do llms.txt do Blume, então as duas configurações include* não têm sobre o que atuar ali.

Autorização

Operações que declaram requisitos de segurança renderizam uma seção Authorization acima de seus parâmetros, e as amostras de código geradas enviam uma credencial de espaço reservado (Authorization: Bearer YOUR_TOKEN, um cabeçalho de chave de API ou uma chave de consulta — o que o esquema exigir). Não há nada para configurar: o Blume lê security da especificação, então a referência sempre corresponde ao que a API realmente aplica.

A semântica do OpenAPI é mantida conforme escrita:

• O security próprio de uma operação sobrescreve o padrão da raiz do documento; security: [] a marca como pública e não renderiza nenhuma seção de Autorização.
• Múltiplas entradas de requisito são alternativas — renderizadas como grupos “ou”; todos os esquemas dentro de uma entrada são exigidos em conjunto. A primeira alternativa alimenta as amostras de código.
• Uma entrada {} vazia significa que a autenticação é opcional para aquela operação, e a seção informa isso.
• Os escopos OAuth2 são listados por esquema; as descriptions de esquema de components.securitySchemes são renderizadas inline.

O renderizador Scalar

O renderizador nativo é o padrão — as páginas de operação, a integração com a busca e o playground Try it acima são todos obra dele. Se você preferir incorporar a interface de referência de API autocontida do Scalar — com sua própria barra lateral, busca, tema e cliente de requisições em uma única rota — defina renderer: "scalar":

openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}

Uma referência renderizada pelo Scalar é uma incorporação autocontida em sua própria rota — ela não se integra à barra lateral, à busca ou ao llms.txt do Blume, e a configuração playground do Blume não se aplica a ela. O que ela segue é o alternador claro/escuro do Blume: a incorporação é fixada no tema da página quando é montada e muda junto com ele, então o alternador de tema do próprio Scalar fica oculto (defina scalar.forceDarkModeState ou scalar.darkMode para devolver o controle do modo de cor ao Scalar). O Scalar traz seu próprio cliente de requisições, que chama sua API de destino diretamente do navegador (a rota playground.proxy não está disponível aqui), então a API precisa permitir requisições de origem cruzada a partir do site de documentação (Access-Control-Allow-Origin). theme se aplica apenas ao renderizador Scalar.

Passando opções do Scalar

theme é um atalho para a opção que a maioria das pessoas usa, mas o Scalar suporta muitas outras. Um objeto scalar encaminha qualquer configuração do Scalar diretamente para a referência incorporada — o Blume não restringe as chaves, então tudo o que o Scalar aceita passa adiante:

openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  scalar: {
    localization: { locale: "es" },   // translate Scalar's own UI
    agent: { disabled: true },         // disable the Scalar Agent
    hideTestRequestButton: true,
    orderSchemaPropertiesBy: "preserve",
  },
}

O i18n do próprio Blume traduz a interface da documentação, mas o Scalar tem um sistema de localização separado — defina scalar.localization.locale para traduzir também a referência incorporada. As opções no objeto scalar prevalecem sobre a configuração derivada do Blume, então tudo que for definido aqui (incluindo theme, customCss ou o content/url da especificação) sobrescreve os padrões do Blume. O mesmo bloco scalar funciona na referência asyncapi.

AsyncAPI

APIs orientadas a eventos usam um bloco irmão asyncapi com o mesmo formato — e o mesmo renderizador nativo. Cada operação send/receive se torna uma página real com tabelas de esquema do payload e dos cabeçalhos da mensagem, parâmetros de canal, bindings de protocolo, uma seção de Autorização derivada dos securitySchemes da especificação (em nível de servidor e de operação, com alternativas como grupos “ou”) e um compositor de mensagens Try it. Apenas a rota padrão difere (/events):

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}

Especificações AsyncAPI 2.x são normalizadas para 3.x automaticamente com o conversor oficial do AsyncAPI, então canais publish/subscribe são mapeados para páginas de operação send/receive com URLs estáveis — atualizar mais tarde o próprio arquivo de especificação através do conversor não move nada. As operações são agrupadas por tag; operações sem tag são agrupadas sob o endereço do seu canal.

As amostras de código são sensíveis ao protocolo, derivadas do binding da operação (ou do protocolo dos seus servidores): wscat e um snippet de WebSocket do navegador para WebSockets, kcat para Kafka, mosquitto_pub/mosquitto_sub para MQTT. codeSamples filtra esse conjunto, da mesma forma que escolhe linguagens no bloco openapi; um protocolo sem uma ferramenta suportada renderiza apenas o exemplo de payload da mensagem em vez de um cliente fabricado.

Tudo o que foi documentado acima se mantém, incluindo o playground: route, sources com label/route, expandSchemas, as flags de indexação por fonte (seoDescriptionSuffix também — a frase gerada nomeia o canal e a ação em vez de um endpoint) e a indexação de busca por resumo e tag da operação.

Definir renderer: "scalar" volta a optar pelo SPA incorporado do Scalar, onde — como no OpenAPI — apenas noindex se aplica. O Scalar não tem um playground AsyncAPI próprio; sua incorporação detecta automaticamente o tipo de documento e renderiza canais, operações, mensagens e uma seção de Modelos, então essa troca abre mão do compositor.

Try it para eventos

Páginas de operação renderizadas nativamente também vêm com um painel Try it aqui, nos mesmos termos do painel OpenAPI: renderizado no servidor já recolhido, com seu JavaScript carregado apenas quando um leitor o abre pela primeira vez.

Seja qual for o protocolo, o painel abre com um editor de payload pré-preenchido a partir dos examples da mensagem — ou, quando a mensagem não declara nenhum, a partir de um valor amostrado do esquema do payload — validado contra o esquema de payload da mensagem conforme você digita. Abaixo dele ficam um campo por parâmetro de canal e um seletor de servidor alimentado pelos servers do canal, com um campo de texto livre para qualquer outra URL. As amostras de código sensíveis ao protocolo andam em sincronia com o formulário exatamente como curl, js e python fazem em uma operação HTTP: o template de endereço do canal é preenchido com os valores de parâmetro que você digita, então um snippet copiado de wscat, WebSocket, kcat ou mosquitto_pub corresponde ao que o formulário diz.

A conexão ao vivo é exclusiva para WebSocket. Em um binding ws ou wss, o painel se conecta à URL de canal resolvida, mostra o estado da conexão e registra cada frame com um timestamp. O AsyncAPI 3 declara uma ação do ponto de vista da API, e o painel segue isso: uma operação receive é uma que a API recebe de você, então ela ganha um botão Send que publica o payload composto; uma operação send apenas transmite mensagens para você, então ela se conecta e registra. Não há lógica de reconexão — uma vez que um socket fecha, ele permanece fechado até você conectar novamente. Kafka, MQTT, AMQP e todos os outros protocolos recebem o compositor e as amostras de CLI copiáveis, e o painel diz isso na própria página: o Blume não simula conectividade com broker a partir de uma aba do navegador.

asyncapi.playground espelha openapi.playground — ligado por padrão com o renderizador nativo, e false é todo o interruptor de desligamento:

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}

O compositor de eventos não coleta credenciais de broker. A seção Authorization de cada página de operação documenta o que o broker espera, e uma conexão WebSocket carrega apenas o que já está na URL. Nada é persistido para operações de evento.