DEV Community

Cover image for How to Document APIs From the CLI
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Document APIs From the CLI

API docs go stale the moment someone edits a spec and forgets to regenerate the reference. The fix is to stop treating documentation as a manual step. If you can produce docs with a single command, you can wire that command into CI and let it run on every merge.

Try Apidog today

Doing it from the terminal has other upsides. Commands are scriptable, they leave a diff you can review, and an AI agent or a CI runner can trigger them without anyone opening a browser. No GUI clicking, no “did you remember to hit export.”

This guide walks the general open route first: turning an OpenAPI file into a standalone HTML reference or a Markdown file with a single command. Then it goes deeper on the Apidog CLI route, which pulls your docs straight out of a live project so the source of truth and the output stay in sync.

If you want more background on the landscape, see our roundup of the top REST API documentation tools and the free API documentation tools worth knowing.

You need one thing to follow along: an OpenAPI 3.x file. Most of these commands accept openapi.yaml or openapi.json interchangeably.

Build an HTML reference with Redocly CLI

Redocly CLI is a fast way to turn an OpenAPI description into a polished, self-contained HTML page. It renders your spec with Redoc and writes the styles, script, and content into one file that you can host anywhere.

Install it globally, or run it with npx if you prefer not to install it:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

Build docs from your spec:

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

By default, Redocly writes redoc-static.html to the current directory. Open it in a browser to view the generated three-panel API reference.

Use --output to choose the destination:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

This workflow has a simple contract:

  1. Provide an OpenAPI or Swagger file.
  2. Run one command.
  3. Publish or archive the generated HTML artifact.

build-docs supports Swagger 2.0 and OpenAPI 3.0/3.1 descriptions. Its scope is intentionally narrow: it generates an API reference, not long-form guides, tutorials, or getting-started content.

Generate Markdown with Widdershins

If your documentation pipeline is Markdown-first, use Widdershins. It converts OpenAPI, Swagger, or AsyncAPI definitions into Slate-compatible Markdown.

Install it from npm:

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

Convert your spec and write the result to a file:

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

Without -o, Widdershins writes to stdout. That makes it useful in shell pipelines:

widdershins openapi.yaml > docs/api.md
Enter fullscreen mode Exit fullscreen mode

You can also configure language tabs for generated code samples:

widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Enter fullscreen mode Exit fullscreen mode

Widdershins works well when you commit generated docs to a repository or feed them into a static-site generator. For a broader Markdown export workflow, see this guide to using an API doc generator with Markdown export.

The limitation is the same as Redocly: both tools read a static file. If openapi.yaml is stale, the generated docs are stale too.

Document from a live project with the Apidog CLI

The integrated route avoids manually syncing a local spec file. Apidog is not open source, but its free tier plus apidog-cli provides a workflow where endpoints, schemas, and written documentation live in one project. The CLI exports from that project on demand, so the output uses the same source your team edits.

Install the CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

For initial setup, including Node and PATH requirements, see the Apidog CLI installation guide.

Authenticate once with a personal access token:

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

The token is stored locally, so you do not need to pass it on every command. Commands run against a project ID. Before using a command in automation, inspect the flags available in your installed version:

apidog --help
Enter fullscreen mode Exit fullscreen mode

Import a spec into the project

If your API already exists as an OpenAPI file, import it into an Apidog project:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import accepts OpenAPI 3.x, Swagger 2.0, Postman, and Apidog formats. After import, the project becomes the live source used by later exports.

Export human-readable docs

Use apidog export to generate OpenAPI, HTML, Markdown, or Postman output. Check your CLI version first, then export the current project documentation to Markdown:

apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

The resulting api-docs.md is generated from the project’s current state.

To export HTML instead:

apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

To export a portable OpenAPI specification:

apidog export --project <projectId> --format openapi --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

If a project contains multiple services, narrow the export scope as needed. Run apidog export --help to check the scope and ID flags supported by your installed CLI version.

Manage written guides, not just the reference

A schema-generated reference is only part of useful API documentation. You also need getting-started guides, authentication walkthroughs, and migration notes.

In Apidog, these live in the project docs tree as Markdown documents. Use the doc command group to manage them:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

The CLI returns JSON results and includes agentHints.nextSteps to guide the next action. When a command requires a JSON payload, you can inspect the expected schema and validate your local file before sending it:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

This helps catch missing fields locally instead of discovering them during a failed command.

Publish a docs site

You can also manage published documentation from the terminal:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

These command groups have different responsibilities:

  • doc: Markdown documents in a project’s API tree.
  • docs-site: hosted public documentation sites.
  • shared-doc: shareable documentation links.

Use docs-site when you want to define or update a public documentation site through automation. Use shared-doc when you need a link to share with a partner.

The repeatable workflow is:

  1. Update the API project or import a changed spec.
  2. Export or publish through the CLI.
  3. Run the same commands from CI on future changes.

Wire it into CI

The main benefit of CLI-based documentation is repeatability. Once a command works locally, it can run in a pipeline.

For example, this GitHub Actions step installs the Apidog CLI, authenticates with a secret token, and regenerates a Markdown API reference:

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

Use repository secrets for both the token and project ID. Do not hardcode credentials in the workflow file.

For file-based workflows, swap the export command for Redocly or Widdershins:

- name: Build HTML API reference
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode 
- name: Generate Markdown API reference
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api.md
Enter fullscreen mode Exit fullscreen mode

At that point, documentation becomes a build artifact instead of a manual task. For the full command reference, see the Apidog CLI complete guide.

Common snags

Wrong or missing project ID. Every Apidog export, doc, and docs-site call needs --project <projectId>. Use the ID from project settings, not the human-readable project name. A project-related command error is often caused by an incorrect ID.

Token not set in CI. apidog login stores the token on the machine that runs it. A fresh CI runner has no saved token, so run login --with-token in the same job before any export. Store the token as a secret.

Stale file exports. Redocly and Widdershins generate output from the file you provide. If openapi.yaml is outdated, the docs are outdated. Exporting from a live Apidog project avoids this file drift.

Guessing flags instead of reading --help. Exact flags for export, doc, docs-site, and shared-doc can vary across CLI versions. Run:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

Use the output from your installed version instead of relying on remembered flags.

Wrapping up

Choose the tool based on the output and source-of-truth model you need:

  • Use Redocly CLI for a standalone HTML API reference.
  • Use Widdershins for Markdown that feeds a docs site or repository.
  • Use the Apidog CLI when you want API reference, written guides, and published documentation managed from one live project.

Every approach is scriptable, so every approach can run in CI. Set it up once, then regenerate documentation whenever the API changes.

Download Apidog to try the CLI export flow against your own project, or learn more about how Apidog fits into an API-first workflow.

Top comments (0)