The docs command generates OpenAPI documentation using the printing press.

It can render a single OpenAPI document, a remote OpenAPI URL, or a directory of specs as an API catalog. By default it also runs vacuum diagnostics and wires the results into the generated docs.

vacuum docs my-openapi-spec.yaml

The default output directory is ./api-docs.

open api-docs/index.html

Learn the feature shape on the Generate API Docs page.

Usage

vacuum docs <openapi-file-url-or-directory>

The input can be:

  • a local OpenAPI file
  • a remote OpenAPI URL
  • a directory of OpenAPI specs
  • omitted when --docs-config points at a config file with scan.root

Common examples

Local OpenAPI file

vacuum docs ./openapi.yaml

Remote OpenAPI URL

vacuum docs https://example.com/openapi.yaml

Change the output directory

vacuum docs ./openapi.yaml --output ./public/api-docs

Use a custom ruleset

vacuum docs ./openapi.yaml -r ./ruleset.yaml

Preview locally

vacuum docs ./openapi.yaml --serve --port 9090

Then open http://127.0.0.1:9090.

Build for static hosting

vacuum docs ./openapi.yaml --publish --base-url https://docs.example.com/api

Generate an API catalog

vacuum docs ./services --output ./api-docs

Use a docs config file

vacuum docs --docs-config ./printing-press.yaml

Common flags

Short Full Input Description
-o --output string Output directory for rendered docs.
--title string Override the API title for a single-spec build.
--catalog-title string Override the catalog title for a directory build.
--docs-config string Path to a printing press docs config file.
--publish bool Build hosted/served HTML assets without starting a local server.
--serve bool Serve the rendered output after building.
--port int Port to use with --serve. Default is 9090.
--base-url string Public base URL to use in generated HTML links.
--base-path string Base path for resolving local file references.
--metrics bool Show live aggregate runtime metrics while rendering.
--no-diagnostics bool Skip lint diagnostics in generated docs.
--no-html bool Skip HTML output.
--no-llm bool Skip LLM and markdown output.
--no-json bool Skip JSON artifact output.

The command also accepts the same core linting inputs used by the rest of vacuum:

Short Full Input Description
-r --ruleset string Use an existing ruleset file for diagnostics.
-f --functions string Path to custom JavaScript function plugins.
--ignore-file string Path to an ignore file.
-p --base string Base URL or base working directory for relative references.
-u --remote bool Load remote references automatically if possible.
-k --skip-check bool Skip checking for a valid OpenAPI document.

Use vacuum docs --help for the exact command flag list. Use the printing press configuration documentation for the full docs config reference.

Config file

The config file keeps larger builds readable:

title: Internal API Catalog
description: API documentation for internal services.
output: ./api-docs
publish: true
metrics: true

scan:
  root: ./services
  include:
    - "**/*.yaml"
    - "**/*.json"
  ignoreRules:
    - "**/vendor/**"
    - "**/testdata/**"

build:
  mode: fast
  maxPools: 4
  workersPerPool: 2

CLI flags win over config file values.

More detail

The docs command is the vacuum entrypoint. The generated documentation experience is explained in the full printing press docs: