The docs command generates OpenAPI and AsyncAPI documentation using the printing press.

It can render a single API document, a remote API 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 <api-file-url-or-directory>

The input can be:

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

Common examples

Local OpenAPI file

vacuum docs ./openapi.yaml

Local AsyncAPI file

vacuum docs ./events.asyncapi.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

Ship the source API contract

The source OpenAPI or AsyncAPI contract is not shipped with generated documentation by default because it may contain sensitive information. Use --include-spec to copy it into the generated site and link rendered source locations back to the contract:

vacuum docs ./openapi.yaml --include-spec

Set includeSpec: true in printing-press.yaml for the same behavior. Pass --include-spec=false to override an enabled configuration value and keep the contract out of the generated output.

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.
--include-spec bool Render and expose the source OpenAPI or AsyncAPI contract with linked source locations.
--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 API 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: