alepha@docs:~/framework/docs/reference/primitives$
cat $uiSwagger.md | pretty
2 min read

#$uiSwagger

#Import

typescript 
1import { $uiSwagger } from "@alepha/ui/swagger";

#Overview

An API explorer page, reading the app's OpenAPI document.

alepha/server/swagger serves the document only ($swagger, at /docs/json by default); this is the viewer, built on @alepha/ui. It lists the operations by tag with a search, and shows each in full: parameters, request body, responses, their schemas, and what Alepha declared about it (the action, who may call it, middlewares, declared errors, timeout) from the x-alepha-* extensions. Each operation can be called from a form built from its schemas, as the signed-in user (the session cookie) or with a token typed in, and a gated one says whether the viewer's permissions reach it.

The page and the document share the /docs prefix by default, which is fine: the page is /docs, the document /docs/json.

ts 
1import { $uiSwagger } from "@alepha/ui/swagger";2import { $swagger } from "alepha/server/swagger";3 4class App {5  openapi = $swagger({ info: { title: "Shop API", version: "1.0.0" } });6  docs = $uiSwagger();7}

It carries the $ prefix to sit with the framework's other declarations at a call site, but it is a plain function wrapping $page, like $pageAdmin. The page component is a lazy chunk, so an app pays for the explorer only when someone opens it.

#Options

Option Type Required Description
name string No The page's name in the router, for router.push(name).
path string No Where the explorer is mounted.
spec string No Where the OpenAPI document is served: <prefix>/json of the app's $swagger, or any OpenAPI 3 document the browser may fetch.
title string No The browser tab's title.
signIn string No Where to sign in, linked from a gated operation when nobody is signed in.
use Middleware[] No Middlewares guarding the page, [$secure({ roles: ["admin"] })] for an explorer only the team should see