apidoc-gen

Generate API documentation from your Go API in one command. Supports Swagger/OpenAPI, Postman, and Docusaurus. This guide covers installation, usage in your backend, and deployment.

CLI

Install

Requires Go 1.22+. For Docusaurus output you also need Node.js/npm.

go install github.com/devenock/api-doc-gen@latest

Or build from source (e.g. for development): git clone ... && go install .

Quick start

From your Go API project root:

# 1) Optional: create config file
apidoc-gen init

# 2) Generate docs (interactive: choose type, framework, etc.)
apidoc-gen generate

# Or non-interactive (e.g. Swagger to ./docs)
apidoc-gen generate --no-interactive --type swagger -o ./docs

Then open docs/index.html (Swagger) or import docs/collection.json (Postman).

Using in your backend codebase

Run apidoc-gen from your Go API project (or pass that path). It reads your repo and writes docs into the folder you choose.

Where to run – From the root of your backend (where go.mod and your routes live). Path defaults to ..
What it reads – go.mod (framework) and .go files. Skips vendor, node_modules, .git, test dirs.
Output – Default ./docs; use -o ./api-docs to change.
Config in repo – Run apidoc-gen init in your backend to add .apidoc-gen.yaml; commit it for shared defaults.
From elsewhere – apidoc-gen generate /path/to/your-api -y --type swagger -o /path/to/your-api/docs

# In your backend repo
cd /path/to/my-go-api
apidoc-gen init
apidoc-gen generate -y --type swagger -o ./docs

# Optional Make target in your backend's Makefile:
# docs:
#   apidoc-gen generate --no-interactive --type swagger -o ./docs

Commands

generate [path] – Scan project and generate docs (path defaults to .)
init – Create .apidoc-gen.yaml in the current directory
completion <shell> – Shell completion (bash, zsh, fish)

Main flags (generate)

-t, --type – swagger | postman | custom
-o, --output – Output directory (default ./docs)
-f, --framework – gin | echo | fiber | gorilla | chi (or leave empty for auto-detect)
-y, --no-interactive – No prompts (use with --type for CI)
-q, --quiet – Less output
-v, --verbose – More detail
--dry-run – Show what would be generated, no files written
--show-config – Print effective config and exit
--title, --version, --base-path, --exclude

Configuration

Config file: .apidoc-gen.yaml in project root. Env vars: APIDOC_TYPE, APIDOC_OUTPUT, etc. Precedence: config file → env → flags.

# Minimal .apidoc-gen.yaml
output: ./docs
type: swagger
framework: ""   # auto-detect

Full reference: docs/CONFIGURATION.md

Docker

Mount your project as the workspace and run generate:

docker build -t apidoc-gen .
docker run --rm -v "$(pwd)":/workspace -w /workspace apidoc-gen generate --no-interactive --type swagger -o ./docs

Replace $(pwd) with your API project path if needed.

CI / scripts

Use --no-interactive (or -y) and set --type so the CLI does not wait for input. Exit codes: 0 = success, 1 = validation error, 2 = runtime error.

apidoc-gen generate -y --type swagger -o ./docs --title "My API"

Help & troubleshooting

In terminal: apidoc-gen --help, apidoc-gen generate --help.

No endpoints found? Set --framework or use -v. Config not read? Use --show-config to debug.

Full guide: docs/TROUBLESHOOTING.md