Guides

CLI

The oaspect command builds a self-contained HTML reference from a spec file, or serves a live preview while you write the spec.

bash
npx oaspect build openapi.yaml -o docs.html
npx oaspect serve openapi.yaml

Install it in a project with npm install --save-dev oaspect to pin the version. Node.js 20 or later.

build

bash
oaspect build <spec> [-o docs.html] [options]

Writes one HTML file containing the viewer script, its styles and your document. Host it anywhere: a bucket, GitHub Pages, an intranet share, an email attachment.

The reference is prerendered: the HTML already holds every operation and model, so the page reads before (and without) JavaScript and search engines index it. The script then attaches to that markup. Pass --no-prerender for a smaller file that renders in the browser only.

In a built file the Source menu and ?url= loading are off (the file documents one API), there is no proxy, and lazy rendering is off so the whole reference is in the HTML.

<spec> is a path or an http(s) URL, JSON or YAML, OpenAPI 3.x or Swagger 2.0. References to other files or URLs are resolved and inlined.

serve

bash
oaspect serve <spec> [--port 8080] [options]

Serves the reference at http://127.0.0.1:8080 and reads <spec> again on every page load: edit the file, reload the page. Try requests go through a built-in proxy, so APIs without CORS work.

The proxy allows any host while the server listens on a loopback address. To listen on the network (--host 0.0.0.0), list the hosts the proxy may call with --proxy-hosts, or turn it off with --no-proxy; the command refuses to expose an open relay.

print

bash
oaspect print <spec> [-o book.html] [--print-style book|apa] [--paper A4|Letter]

Writes an HTML file that opens as a printable book: cover, contents with page numbers, a chapter per tag, the models as an appendix. Print it from the browser to get a PDF. See Print and PDF.

docs

bash
oaspect docs build <dir> [-o docs.html]
oaspect docs bundle <dir> [-o docs.json]
oaspect docs serve <dir> [--port 8080]
oaspect docs print <dir> [-o book.html]

The same for a folder of Markdown files: one HTML file, a JSON bundle for Oaspect.docs({ docsUrl }), a live preview, or a printable book. --title, --edit-url, --locale, --theme and --logo apply. See Developer docs.

Options

OptionCommandsDescription
-o, --output <file>build, printOutput file. Default: the spec's name with .html (-book.html for print).
--title <text>bothPage and header title. Default: info.title.
--locale <code>bothStarting UI language (en, tr, ar…). Readers can still switch.
--theme <light|dark>bothForce a theme.
--logo <url>bothHeader logo image.
--no-prerenderbuildRender in the browser only.
--print-style <book|apa>printBook style. Default book.
--paper <A4|Letter>printPaper size. Default A4.
--port <number>servePort. Default 8080.
--host <address>serveAddress to listen on. Default 127.0.0.1.
--proxy-hosts <list>serveComma-separated hosts the proxy may call.
--no-proxyserveTurn the Try proxy off.
-h, --helpShow help.
-v, --versionShow the version.

In CI

Build the reference with your API and publish it with the rest of your static files:

yaml
# .github/workflows/docs.yml (excerpt)
- run: npx [email protected] build openapi.yaml -o public/docs.html --title "Acme API"

The output depends only on the spec and the oaspect version, so pin the version for reproducible builds.