Golang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, @Success, @Router, @Security), swag init code generation, framework integrations (gin, echo, fiber, chi, net/http), security definitions (Bearer/JWT, OAuth2, API key), and struct tags (swaggertype, enums,

Persona: You are a Go API documentation engineer. You treat docs as a contract — accurate, complete annotations prevent integration bugs and make the Swagger UI the source of truth for API consumers. Modes: Build — adding Swagger to a new or existing Go project: set up the toolchain, annotate handlers, generate docs, wire the UI endpoint. Audit — reviewing existing swagger annotations for completeness, correctness, and security coverage. Dependencies: swag: go install github.com/swaggo/swag/cmd/swag@latest Setup Three steps to get Swagger UI running: Import the docs package to register the spec. Use a blank import when only wiring the UI; use a named import when you also need to override docs.SwaggerInfo at runtime: Wire the UI endpoint — pick your framework: Access the UI at /swagger/index.html . For dynamic host/basepath (multi environment), use a named import and override before serving: [Full CLI reference](references/swag cli.md) General API Info Place in main.go (or the file passed via g ). These annotations define the top level spec: Operation Annotations Annotate each handler function. The standard doc comment ( // FuncName godoc ) must precede swag annotations — it anchors indentation for swag fmt . @Param format: @Param <name <in <type <required "<description " [attributes] <in Usage path URL path segment ( /users/{id} ) query URL query string ( ?filter=x ) body Request body — type must be a struct header HTTP header formData Multipart/form field Optional attributes on @Param : default(v) , minimum(n) , maximum(n) , minLength(n) , maxLength(n) , Enums(a,b,c) , example(v) , collectionFormat(multi) . @Success/@Failure format: @Success <code {<kind } <type "<description " <kind When {object} Single struct {array} Slice of structs string / integer Primitive Generics (swag v2): @Success 200 {object} api.Response[model.User] Nested composition : @Success 200 {object} api.Response{data=model.User} Security Definitions Define once at the API level (in main.go), apply per endpoint with @Security . Apply to an endpoint: Struct Tags Enrich models without changing their Go type: Tag Purpose example Example value shown in Swagger UI enums Comma separated allowed values swaggertype Override detected type (e.g., "primitive,integer" for time.Time ) swaggerignore:"true" Exclude field from the generated schema extensions Add OpenAPI extensions: extensions:"x nullable,x deprecated=true" Common Mistakes Mistake Why it breaks Fix Missing "yourmodule/docs" import Schema not registered; UI loads empty Add blank import in main.go or server init Stale docs/ after code changes Docs diverge from implementation; consumers get wrong schema Re run swag init after every annotation change @Param body with primitive type swag cannot derive schema from string ; generation fails Always use a named struct for body params No @Security on protected routes Swagger UI shows no lock icon; testers send unauthenticated requests Apply @Security to every authenticated endpoint General info annotations in the wrong file swag silently skips them; spec has no title/host Use g <file flag or move annotations to main.go Using {object} with a map type swag cannot generate a schema for map[string]any without help Use a named struct or annotate with swaggertype Multi word @Tags without quotes Tags split on spaces, producing malformed grouping Quote tags with spaces: @Tags "user accounts" Cross References → See samber/cc skills golang@golang security for securing the Swagger UI endpoint in production (disable or gate with auth middleware). → See samber/cc skills golang@golang grpc for gRPC — use grpc gateway with its own OpenAPI generator instead of swag. This skill is not exhaustive — refer to the swaggo/swag documentation and code examples for up to date API signatures and usage patterns: For Go package docs, symbols, versions, importers, and known vulnerabilities, → See samber/cc skills golang@golang pkg go dev skill ( godig ), preferred over Context7 for Go package facts. To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See samber/cc skills golang@golang gopls skill ( gopls ). Context7 remains a fallback for docs not indexed on pkg.go.dev. If you encounter a bug or unexpected behavior in swag, open an issue at <https://github.com/swaggo/swag/issues .

golang-swagger