skills.rest
asarchami
asarchamiCOMMUNITY
Explore all skills by this author →
GitHub

go-swagger

Generates and audits swag OpenAPI annotations for Go API handlers.

1|2|Updated Nov 25, 2017
Search Tags:#openapi#go#swagger#api documentation#annotations#gin#swag init
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill go-swagger-asarchami
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: go-swagger
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/go/go-swagger
Command: npx skills add https://github.com/asarchami/dotfiles --skill go-swagger-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Go APIs documented with swag often drift out of sync with the code: missing @Param entries, stale generated docs, unsecured endpoints lacking @Security, and general info silently dropped because it lives in the wrong file. This Skill enforces a complete annotation contract so the Swagger UI always matches the actual handlers. ## Core Features & Use Cases - Annotation authoring: Step-by-step guidance for @Summary, @Param, @Success, @Router, and @Security on every handler, plus general API info and security definitions in main.go. - Generation workflow: Covers swag init, swag fmt, framework wiring for Gin, Echo, Fiber, and net/http, and regenerating docs/ after every change. - Audit checklist: Verifies param kinds, response object types, security coverage, and that committed swagger.json matches the current code. - Use Case: You add a new endpoint to a Gin service and need the Swagger UI to show its parameters, responses, and Bearer auth requirement without breaking existing docs. ## Quick Start Annotate my Go handlers with swag comments and generate the Swagger docs for this API.

Frequently Asked Questions about go-swagger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add Swagger documentation to a Go API?▼

Install swag, add general info annotations (@title, @host, @BasePath) to main.go, annotate each handler with @Summary, @Param, @Success, and @Router, then run swag init to generate the docs/ folder. Blank-import the docs package and wire a swagger handler for your framework.

How do I document request bodies with swag annotations?▼

Use @Param with the body location and reference a named struct, for example @Param req body model.CreateUserRequest true "input". Body params cannot use primitives or map[string]any because swag cannot derive a schema from them.

Does swag work with Gin, Echo, and Fiber?▼

Yes, swaggo provides integration packages for Gin (gin-swagger), Echo (echo-swagger), Fiber (fiber-swagger), and net/http or Chi (http-swagger). All of them rely on the shared swaggo/files package to serve the UI.

Why is my Swagger UI empty or missing the API title?▼

An empty UI usually means the blank import _ "yourmodule/docs" is missing. Missing title or host happens when general info annotations are not in the file passed to swag init via -g, since swag silently skips them otherwise.

How do I add JWT Bearer auth to Swagger docs in Go?▼

Declare @securityDefinitions.apikey Bearer with @in header and @name Authorization in main.go, then add @Security Bearer to every protected endpoint. The Swagger UI will show a lock icon and prompt for the token.

Why does swag fmt not format my annotation comments?▼

swag fmt requires a standard godoc line like // FuncName godoc immediately before the first @ annotation. Without that anchor comment the formatter cannot determine indentation and skips the block.

Related Skills

Explore More Software Engineering Skills→
witoohwitooh

api-doc-gen

Generate and validate Markdown API documentation from Go source code.

Community
Advanced
albanistrefialbanistrefi
4

umbraco-openapi-client

Generate an authenticated TypeScript OpenAPI client for Umbraco backoffice APIs.

Community
Intermediate
eleva-labseleva-labs

api-validate

Validate API implementations against OpenAPI specifications and contracts.

Official
Intermediate
saddam-eng-techsaddam-eng-tech

go-grpc-gateway

Generate gRPC-Gateway setup with HTTP annotations, CORS, and OpenAPI spec.

Community
Advanced