Generate Go API docs from source annotations with Swag
Use Swag when an agent needs to turn Go handler annotations into reviewable Swagger 2.0 documentation before API docs, clients, or release checks depend on it.
npx skills add agentskillexchange/skills --skill generate-go-api-docs-from-source-annotations-with-swag
Use Swag when an operator wants an agent to maintain API documentation from the Go source tree instead of hand-writing a separate OpenAPI artifact. The workflow is to inspect the Go service, add or repair Swag-compatible annotations around handlers and API metadata, run swag init, review the generated docs package and Swagger output, then hand the result to documentation, client-generation, or CI validation steps.
What this skill actually does
This is skill-shaped because the repeatable job is narrow: keep Go API source annotations and generated Swagger 2.0 docs synchronized. It is not a generic Swagger listing, API design framework, or hosted documentation product; invoke it specifically when the source of truth is a Go codebase and the agent can edit annotations, regenerate docs, and surface diffs for review.
Inputs and prerequisites: Go 1.19 or newer, a Go API project with handler comments or planned Swag annotations, and access to run the Swag CLI or Docker image.
Setup notes: Install with go install github.com/swaggo/swag/cmd/swag@latest, then run swag init in the project root containing main.go. If the general API annotations live elsewhere, run swag init -g path/to/file.go and import the generated docs package as required by the upstream README.
Source and verification boundary: use https://github.com/swaggo/swag as the canonical source before running the workflow; keep generated docs and annotation edits reviewable against the upstream Swag command behavior.
Framework fit: publish this as Multi-Framework because Swag is an agent-runtime-agnostic documentation generator that can be invoked by Codex, Claude Code, OpenClaw, Cursor, or other coding agents inside a Go repository.