GoDoc Live

API documentation that writes itself.
Point it at your Go code. Get interactive docs. No annotations required.

Your API docs are already in your code. GoDoc Live just reads them.

GoDoc Live uses go/ast and go/types — the same packages the Go compiler uses — to walk your source, extract every route, parameter, request body, response type, and auth pattern, then generates an interactive docs site and OpenAPI 3.1.0 spec. No YAML to maintain. No annotations to add. No code to change.

Quickstart

go install github.com/syst3mctl/godoclive/cmd/godoclive@latest
godoclive generate ./...
open docs/index.html

Or serve with live reload — docs update as you save:

godoclive watch --serve :8080 ./...

Why GoDoc Live?

API docs written by hand drift. Someone adds a query param and forgets the spec. Someone changes a status code and the YAML still says 200. Six months later your docs and your code contradict each other.

GoDoc Live has no drift problem — it reads the source of truth directly.

What It Detects

Supported Routers

CLI Reference

godoclive generate [packages]

godoclive generate ./...
godoclive generate --output ./api-docs --theme dark ./...
godoclive generate --format single ./...         # Single self-contained HTML (~300KB)
godoclive generate --serve :8080 ./...           # Generate + serve
godoclive generate --openapi ./openapi.json ./... # Also emit OpenAPI 3.1.0 spec

godoclive analyze [packages]

Run analysis and print a contract summary to stdout.

godoclive analyze ./...
godoclive analyze --json ./...        # Machine-readable output
godoclive analyze --verbose ./...     # Show unresolved details

godoclive openapi [packages]

Generate an OpenAPI 3.1.0 specification without the HTML docs.

godoclive openapi ./...                          # Outputs ./openapi.json
godoclive openapi --output ./api.yaml ./...      # YAML format (inferred from extension)
godoclive openapi --server https://api.example.com ./...

godoclive watch [packages]

Watch for .go file changes and regenerate docs automatically. Supports the same flags as generate.

godoclive watch --serve :8080 ./...

When --serve is set, the browser auto-reloads via Server-Sent Events — edit your code, save, see updated docs instantly.

godoclive validate [packages]

Report analysis coverage — what percentage of endpoints are fully resolved.

godoclive validate ./...
godoclive validate --json ./...

Configuration

.env file

Create a .env file in your project root to set the API base URL for the Try It panel:

API_URL="http://localhost:8080"

Precedence: --base-url CLI flag > .env API_URL > .godoclive.yaml base_url > default.

.godoclive.yaml

Create an optional .godoclive.yaml in your project root:

# Project metadata
title: "My API"
version: "v2.1.0"
base_url: "https://api.example.com"
theme: "dark"

# Exclude endpoints from documentation
exclude:
  - "GET /internal/*"
  - "* /debug/*"

# Override or supplement analysis results
overrides:
  - path: "POST /users"
    summary: "Register a new user account"
    tags: ["accounts"]
    responses:
      - status: 409
        description: "Email already registered"
      - status: 503
        description: "Service temporarily unavailable"

# Auth configuration
auth:
  header: "Authorization"
  scheme: "bearer"

# OpenAPI 3.1.0 spec metadata
openapi:
  description: "Full description of the API."
  contact:
    name: "API Support"
    url: "https://example.com/support"
    email: "support@example.com"
  license:
    name: "MIT"
    url: "https://opensource.org/licenses/MIT"
  servers:
    - url: "https://api.example.com"
      description: "Production"
    - url: "https://staging.example.com"
      description: "Staging"

Zero configuration is always valid — the tool produces useful output without any config file.

How It Works

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  1. Load  │──▶│2. Detect │──▶│3. Extract│──▶│4. Resolve│
│ go/pkgs   │   │ chi/gin  │   │  routes  │   │ handlers │
└──────────┘   └──────────┘   └──────────┘   └──────────┘
                                                    │
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────▼────┐
│8.Generate│◀──│ 7. Auth  │◀──│ 6. Map   │◀──│5.Contract│
│ HTML/CSS │   │ middleware│   │ structs  │   │params/body│
└──────────┘   └──────────┘   └──────────┘   └──────────┘

1. Load — Uses go/packages to load and type-check your Go source code
2. Detect — Identifies the router framework (chi, gin, gorilla/mux, or stdlib) from imports
3. Extract — Walks main() and init() AST to find route registrations
4. Resolve — Resolves handler expressions to function declarations
5. Contract — Extracts path params, query params, headers, body, and responses from handler ASTs
6. Map — Converts types.Type into recursive TypeDef with JSON tags, examples, and field metadata
7. Auth — Scans middleware function bodies for authentication patterns
8. Generate — Transforms endpoint contracts into an interactive HTML documentation site

All analysis uses go/ast and go/types — no runtime reflection, no annotations, no code generation.

Programmatic API

Use GoDoc Live as a library in your own tools:

import "github.com/syst3mctl/godoclive"

// Analyze a project
endpoints, err := godoclive.Analyze(".", "./...",
    godoclive.WithTitle("My API"),
)

// Generate HTML docs
err = godoclive.Generate(endpoints,
    godoclive.WithOutput("./api-docs"),
    godoclive.WithFormat("single"),
    godoclive.WithTheme("dark"),
)

// Generate HTML docs + OpenAPI spec in one call
err = godoclive.Generate(endpoints,
    godoclive.WithOutput("./api-docs"),
    godoclive.WithOpenAPIOutput("./openapi.json"),
)

// Generate only an OpenAPI 3.1.0 spec (returns JSON bytes)
specBytes, err := godoclive.GenerateOpenAPI(endpoints,
    godoclive.WithTitle("My API"),
    godoclive.WithVersion("v2.1.0"),
)

Accuracy (Phase 1)

Measured across 12 testdata projects with 50 endpoints:

Performance

Benchmarks run on Apple M2 Pro, Go 1.25, using the testdata projects included in the repository. Run them yourself: go test -bench=. -benchmem ./internal/pipeline/ ./internal/generator/

Analysis pipeline

The dominant cost is go/packages type-checking — loading and type-checking the full dependency tree via NeedDeps. Route extraction, contract analysis, struct mapping, and type lookups together add less than 5 ms on top. Memory is not retained after the call; it is held only during analysis and released when the returned []EndpointDef is in scope.

The type-lookup path was optimised in v0.1.0: a single packages.Visit traversal builds a pkgPath → name → types.Type index at pipeline start, replacing the previous O(N×routes×deps) repeated traversals with O(1) map lookups.

Documentation generation

Single-file mode writes more memory (≈10× more per run) because all CSS, JS, and WOFF2 font assets are base64-encoded and inlined into one self-contained HTML file (~300 KB on disk).

Roadmap

Contributing

See CONTRIBUTING.md for guidelines on adding new router extractors, structuring testdata, and running the test suite.

License

MIT — see LICENSE.

Made with love and go/ast