# Golang Swagger

> Add, update, or review swaggo/swag annotations and generated OpenAPI documentation: operation contracts, schemas, security declarations, framework integration, generator wiring, and drift checks. Use when a Go API uses or deliberately selects the swaggo annotation workflow.

- Skill: `reagin/golang-swagger` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add reagin/golang-swagger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reagin/golang-swagger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: reagin (https://skillmd.com/u/reagin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reagin/golang-swagger

---


# Swaggo API Documentation

Treat the generated specification as a consumer contract derived from annotations and code. Preserve the project's generator version, framework integration, output location, and ownership rules.

## Inspect the existing toolchain

Before editing:

1. Read go.mod, generator pinning, go:generate or build commands, API entry point, router registration, annotations, generated files, and CI drift checks.
2. Determine which files are sources and which are generated.
3. Confirm the target Swagger or OpenAPI dialect and the installed swaggo version from project evidence.
4. Identify public versus internal routes and whether documentation UI is enabled in each environment.
5. Check the repository's error envelope, authentication schemes, naming, tags, and compatibility policy.

Do not replace a spec-first workflow or hand-edit generated output. If the project has no chosen documentation tool, compare approaches before adding swaggo.

Read [annotation recipes](references/annotation-recipes.md) when writing `@Param`, `@Success`, `@Failure`, `@Router`, `@Security`, general metadata, or model tags. Adapt the examples to the pinned generator rather than treating them as a complete grammar.

## Document the real contract

For each operation, reconcile annotations with router and handler behavior:

- HTTP method and exact path;
- path, query, header, form, and body parameters;
- requiredness, defaults, ranges, enums, formats, and collection behavior;
- request and response content types;
- success and error status codes;
- response body and headers;
- authentication and authorization requirements;
- deprecation and compatibility notes.

Keep parameter location and type paired correctly: path parameters must match router placeholders, request bodies should use named request types, and array/object response annotations must match the runtime JSON shape. Distinguish a response with no body from an empty JSON object.

Use named request and response types when they make the schema stable and understandable. Avoid exposing internal persistence structs, secrets, write-only credentials, or fields omitted by the actual serializer. Align JSON names and nullability with runtime encoding.

Document every behavior consumers can observe, but do not invent validation or status codes that the implementation does not enforce. When the desired contract differs from code, make the discrepancy explicit and change the authoritative side only within user scope.

## General metadata and security

Keep title, version, description, contact, host, base path, and schemes consistent with the deployment model. Avoid hardcoded environment hosts when the existing integration supports runtime configuration.

Define each authentication scheme once and apply the correct requirement to every protected operation. Distinguish alternatives from combinations that require multiple schemes. Documentation is not enforcement: verify the router's middleware and handler authorization separately.

The documentation UI can reveal endpoints, schemas, and examples. Preserve existing exposure policy. Do not enable it publicly in production or add an unauthenticated route without an explicit decision.

## Work with annotations safely

Follow the syntax supported by the project's pinned swaggo version rather than a copied annotation catalog. Consult its official versioned documentation for:

- general API metadata;
- operation annotations;
- parameter and response grammar;
- model overrides and custom types;
- security definitions;
- parser flags and framework integration.

Keep annotations near their owning handler when that matches project convention. Prefer concise descriptions and reusable schemas over large duplicated blocks. If parser flags include dependencies or internal packages, understand the exposure and build-time cost before broadening them.

Generated documentation should be reproducible. Do not include timestamps, machine-local paths, or environment-specific data unless the established generator intentionally does so.

## Generate and review

Use the repository's pinned generation command. Before running it, check command help for the installed version and ensure the working tree lets you distinguish generated changes.

Review the generated diff for:

- removed or renamed operations;
- schema name and required-field changes;
- accidental internal types or routes;
- changed security requirements;
- unstable ordering or unrelated churn;
- consistency across generated formats committed by the project.

Do not accept a successful generator exit as proof of correctness.

## Verification

Run focused Go tests and the repository's API documentation checks. When practical, parse or validate the generated specification with an existing pinned tool and compare representative routes against router behavior.

For each changed endpoint, verify one success response and relevant failure contracts, including authentication. Check that documentation imports or registration code are included in the built application only where intended.

If generation cannot run because the pinned tool or dependencies are unavailable, update source annotations only when safe and report which generated artifacts remain unverified.