Reference UIs

specReference from better-supabase/spec answers a request with an HTML page that renders your OpenAPI document in a reference UI. Serve it next to the specResponse route that serves the document:

import { specResponse } from "better-supabase/spec";
import { api } from "../../../lib/api";

const { document } = api.openapi();

export const GET = (request: Request) => specResponse(document, request);
export const HEAD = GET;

import { specReference } from "better-supabase/spec";

export const GET = (request: Request) =>
  specReference({ specUrl: "/api/openapi.json", csp: true }, request);
export const HEAD = GET;

The page loads the document from specUrl in the browser, so the two routes stay independent: the document keeps its ETag, and the page holds no copy of it. In Hono, mount both on the app:

import { createHono } from "better-supabase/hono";
import { specReference, specResponse } from "better-supabase/spec";
import { api } from "./lib/api";
import { betterSupabase } from "./lib/supabase";

const bs = createHono(betterSupabase);
const { document } = api.openapi();

export const app = bs
  .app()
  .get("/api/openapi.json", (c) => specResponse(document, c.req.raw))
  .get("/api/docs", (c) =>
    specReference({ specUrl: "/api/openapi.json", ui: "redoc" }, c.req.raw),
  );

specReference(options, request) answers GET and HEAD (headers only), and 405 with Allow: GET, HEAD for any other method. The response is text/html; charset=utf-8 with Cache-Control: no-cache unless you pass cacheControl.

The five UIsCopy Anchor Link

ui picks the UI. Scalar is the default.

SPEC_UIS lists the names and SPEC_UI_PACKAGES the package and version of each. An unknown name throws a TypeError.

config passes options to the UI: Scalar's configuration, the options of Swagger UI and Redoc, or attributes of the Elements and RapiDoc components. title sets the page title (default API reference).

specReference(
  {
    specUrl: "/api/openapi.json",
    ui: "swagger",
    title: "CRM API",
    config: { deepLinking: true, tryItOutEnabled: true },
  },
  request,
);

Elements renders with router: "hash" and layout: "sidebar" unless config overrides them.

Where the assets come fromCopy Anchor Link

By default the page loads each UI from jsDelivr (https://cdn.jsdelivr.net/npm) at the pinned version, and every script and stylesheet tag carries a Subresource Integrity hash with crossorigin="anonymous", so the browser refuses a file that changed.

assets changes that:

import { specReference } from "better-supabase/spec";

export const GET = (request: Request) =>
  specReference(
    {
      specUrl: "/api/openapi.json",
      ui: "scalar",
      assets: { scripts: ["/vendor/scalar/standalone.js"] },
      csp: true,
    },
    request,
  );

Self-hosted files carry no integrity attribute: you serve them, so you control what they contain.

Content Security PolicyCopy Anchor Link

nonce sets a nonce on every script and style tag the page writes, for a policy your app already sends. csp: true sends a policy with the response and generates a nonce when you don't pass one:

The asset origins are those of the URLs the page loads (jsDelivr by default); self-hosted relative paths add none. specReferenceCsp({ nonce, ui, assets }) returns the same policy string, for an app that sets its headers elsewhere.

The HTML aloneCopy Anchor Link

specReferenceHtml(options) returns the page as a string, with the same options minus csp and cacheControl. Use it to write a static file or to build your own response. spec emit --ui uses it to write openapi.html next to openapi.json.

Sign in from ScalarCopy Anchor Link

scalarPreset(document, options) adds Scalar's x-scalar-* extensions to an OpenAPI document, so the "try it" panel can sign in through the OAuth flows the document declares. It returns a copy. Use it in a transform:

import { scalarPreset } from "better-supabase/spec";

const { document } = api.openapi({
  transform: ({ document }) =>
    scalarPreset(document, {
      clientId: "docs",
      redirectUri: "https://example.com/api/docs",
    }),
});

Use a public client: the client id ends up in the document every visitor can read.