Scalar

Incorpore a interface autocontida de referência de API do Scalar em uma única rota, repassando diretamente qualquer opção do Scalar.

O renderizador próprio do Blume é o que openapi(), asyncapi() e graphql() oferecem: uma página de verdade para cada operação, que aparece na sua barra lateral, na busca e no llms.txt, com um playground Try it. Se você preferir incorporar a interface autocontida de referência de API do Scalar, liste um adaptador scalar() de blume/reference. Essa interface traz barra lateral, busca, tema e cliente de requisições próprios em uma única rota. O adaptador recebe um documento OpenAPI ou AsyncAPI, e o Scalar detecta qual dos dois é:

import { defineConfig } from "blume";
import { scalar } from "blume/reference";

export default defineConfig({
  reference: [
    scalar({
      spec: "./openapi.yaml",
      theme: "purple", // a Scalar theme name
    }),
  ],
});

Isso monta o embed em /reference. spec pode ser uma URL http(s) ou o caminho de um arquivo local. Uma URL é carregada pelo navegador. Um arquivo local é lido no build e embutido na página, para que ela continue autocontida. route muda a rota do embed. sources publica vários documentos, cada um na sua própria rota, seguindo as mesmas regras de label/route dos adaptadores nativos:

reference: [
  scalar({
    route: "/api",
    sources: [
      { label: "Public API", spec: "./public.json" },   // → /api/public-api
      { label: "Legacy API", route: "/legacy", spec: "./legacy.json", noindex: true },
    ],
  }),
],

Um embed do Scalar e páginas nativas podem ficar lado a lado na lista, desde que tenham rotas diferentes. Você pode, por exemplo, usar um adaptador openapi() para a API atual e um adaptador scalar() para uma API legada. Assim como qualquer referência, o embed não cria sozinho uma aba no cabeçalho. Para exibi-lo, aponte uma aba de navegação para a rota dele.

O que o embed não faz

Uma referência renderizada pelo Scalar é uma página autocontida, na sua própria rota. Ela não entra na barra lateral, na busca nem no llms.txt do Blume. Por isso, dos controles por fonte dos adaptadores nativos, só o noindex vale aqui: ele adiciona metadados de noindex para crawlers e deixa a página fora do sitemap. Não existe codeSamples, expandSchemas nem playground para configurar. O Scalar tem o próprio cliente de requisições, que chama a sua API de destino diretamente do navegador. A rota playground.proxy do Blume não está disponível aqui, então a API precisa aceitar requisições cross-origin vindas do site da documentação (Access-Control-Allow-Origin).

O embed acompanha o seletor de modo claro/escuro do Blume. Ao ser montado, ele assume o tema da página e passa a mudar junto com ela, por isso o seletor de tema do próprio Scalar fica oculto. Para devolver o controle do modo de cor ao Scalar, passe forceDarkModeState ou darkMode. Sem um theme, o Blume aplica a cor de destaque e o raio de borda dele por cima do tema padrão do Scalar. Um theme nomeado substitui isso. O adaptador declara @scalar/astro como dependência de runtime, então o projeto gerado só inclui esse pacote quando há um adaptador scalar() configurado.

Passando opções do Scalar

theme é a opção que a maioria das pessoas procura, mas o Scalar aceita muitas outras. Além de spec, sources, route e theme, qualquer chave que você passar para scalar() é repassada sem alterações como configuração do Scalar para a referência incorporada. O Blume não filtra as chaves, então tudo o que o Scalar aceita é repassado. Só valem valores JSON, porque a configuração é embutida na página gerada:

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

O i18n do Blume traduz a interface da documentação, mas o Scalar tem um sistema de localização separado. Para traduzir também a referência incorporada, defina localization.locale. As opções repassadas têm prioridade sobre a configuração que o Blume gera, então o que você definir aqui substitui os padrões do Blume. Isso inclui customCss e o content/url da spec. A única chave que não pode ser repassada é o sources multidocumento do próprio Scalar. Esse nome é usado pelo Blume, e cada fonte do Blume vira uma página separada.

Documentos AsyncAPI

Se você apontar spec para um documento AsyncAPI, o embed renderiza canais, operações, mensagens e uma seção Models. O Scalar não tem um playground próprio para AsyncAPI. Por isso, ao escolher o embed em vez de asyncapi(), você abre mão do compositor de eventos do Blume. Schemas GraphQL não têm embed do Scalar: a referência graphql() é sempre renderizada nativamente.