vacuum v0.27.0 can generate API documentation directly from an OpenAPI specification.

It uses the printing press engine to turn OpenAPI contracts into static HTML, JSON artifacts, and agent-readable markdown output.

The important vacuum bit is diagnostics: vacuum can lint the spec first, then pipe the located results into the generated documentation so quality issues appear where they matter.

vacuum docs my-openapi-spec.yaml

This writes docs to ./api-docs by default.

open api-docs/index.html
Screen shot of generated API documentation
Generated OpenAPI documentation, powered by the printing press.

What gets generated?

By default, vacuum docs generates three output families:

  • Human-friendly HTML documentation.
  • Agent-friendly markdown, AGENTS.md, and llms.txt files.
  • JSON artifacts for tools that need structured generated data.

The same command can produce docs for people browsing locally on a file system, or who want to bundle docs with a release and host them. and concise API context for agents that means no parsing of raw OpenAPI documents.

The default output works from straight from disk. Zip it, attach it to a release, commit it, or open api-docs/index.html directly.

For the full generated file tree, see the printing press outputs documentation.

Diagnostics built in

vacuum docs runs diagnostics by default. You can disable them with --no-diagnostics if you just want the documentation.

The diagnostics are actually a much nicer experience than the html-report output.

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

Problems are shown inside the generated docs, attached to the operations and models that contain them. A dedicated diagnostics page is generated as well.

Screen shot of generated diagnostics page
vacuum diagnostics rendered inside generated API documentation.

As I said, if you just want documentation without lint diagnostics:

vacuum docs my-openapi-spec.yaml --no-diagnostics

For more detail, see the printing press diagnostics documentation.

Publish or preview

The default mode is designed for local files and offline sharing.

Use --publish when the output will be served by GitHub Pages, S3, Netlify, Cloudflare Pages, or any static host:

vacuum docs my-openapi-spec.yaml --publish --output ./api-docs

Use --serve to preview the published layout locally:

vacuum docs my-openapi-spec.yaml --serve --port 9090

Then open http://127.0.0.1:9090.

The full static, published, and served behavior is covered in the printing press rendering modes documentation.

Build an API catalog

Pass a directory instead of a single file and vacuum will build an entire API catalog.

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

The catalog scans for OpenAPI documents, groups specs by service and version, and renders a top-level portal plus full documentation for every discovered spec.

Screen shot of generated API catalog render pools
A generated API catalog can organize many services and versions.

For large catalogs, use a docs config file to keep the command clean:

title: Internal API Catalog
output: ./api-docs
publish: true
metrics: true

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

build:
  mode: fast
  maxPools: 4
  workersPerPool: 2

Then run:

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

For the full catalog model, see the printing press API catalog documentation.

Agentic output

Raw OpenAPI is a poor input for agents. It forces them to parse a contract, chase references, understand composition, and build enough context to answer a basic API question.

vacuum docs generates agent-ready files so agents can start with a map instead of a pile of YAML:

  • AGENTS.md
  • llms.txt
  • llms-full.txt
  • llms-models.txt
  • llms-operations.txt
  • per-operation markdown
  • per-model markdown
  • structured JSON artifacts

The full agent workflow is covered in the printing press agentic AI documentation.

Learn more

This page covers the vacuum entrypoint. The deeper documentation for the generated experience lives on pb33f.io:

For command examples, see the docs command page.