cmd

Documentation

Overview

openapi.go — generate OpenAPI 3 YAML for the public + admin servers from the same handler/DTO AST walk that produces docs/reference/http-api.md.

Why this exists. The old hand-written docs/api/{admin,public}-api.yaml drifted from the handlers (multiple audits caught wire-shape mismatches) and was deleted in the v2 docs revamp. The repo's stance is that the handler source + DTO struct tags are the only ground truth (see the memory note `feedback_openapi_not_ground_truth`). This emitter restores the machine-readable OpenAPI surface for tooling consumers (Swagger UI, openapi-validator, client codegen) **without** reintroducing drift: the YAML is produced from the same `buildHTTPModel` walk as the Markdown reference, so a handler / DTO change updates both in lockstep when `make docs-gen` runs.

Per-route request/response/error metadata comes from the existing `routeBodyHints` map (also the source the Markdown reference uses). That map carries `{{dto:X}}` placeholders + `**Response NNN**` markers + `**Errors** — NNN \`code\“ lists; this file parses those strings into structured OpenAPI operation parts. Any route without a hint entry gets a minimal but valid operation entry — losing schema-bound bodies for it, but never producing an invalid spec.

Output: docs/api/admin-api.yaml and docs/api/public-api.yaml. Wired into `make docs-gen` via the `all` subcommand, and into `make docs-check`'s `git diff --exit-code` guard so a stale file fails CI.

Package cmd wires up the cobra command tree for docsgen.

The root command exposes a shared --out flag that holds the output directory for generated reference docs. Subcommands inherit this flag and resolve their own target file underneath it.

Index

• Constants
• func NewRoot() *cobra.Command

Constants

const DefaultOutDir = "docs/reference"

DefaultOutDir is the default directory where generated reference docs land. Callers may override with --out.

const GeneratedByHeader = "<!-- generated by tools/docsgen; do not edit. Re-run: make docs-gen -->"

GeneratedByHeader is the canonical first line that every generated file must start with. The docs-check tooling greps for this marker to distinguish hand-written from machine-written reference pages.

Functions

func NewRoot

func NewRoot() *cobra.Command

NewRoot returns the root cobra command with all subcommands attached. It is exported so main and tests can construct a fresh command tree.