Labsco
samber logo

golang-swagger

★ 2,400

by samber · part of samber/cc-skills-golang

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, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger,...

🔥🔥🔥✓ VerifiedFreeQuick setup
#email#git#security
🧩 One of 7 skills in the samber/cc-skills-golang package — works on its own, and pairs well with its siblings.

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, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger,...

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by samber

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, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger,... npx skills add https://github.com/samber/cc-skills-golang --skill golang-swagger Download ZIPGitHub2.4k 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

General API Info

Place in main.go (or the file passed via -g). These annotations define the top-level spec:

Copy & paste — that's it
// @title My API
// @version 1.0
// @description Short description of the API.
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https

// @contact.name API Support
// @contact.email [email protected]
// @license.name Apache 2.0

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and the JWT token.

Operation Annotations

Annotate each handler function. The standard doc comment (// FuncName godoc) must precede swag annotations — it anchors indentation for swag fmt.

Copy & paste — that's it
// ShowAccount godoc
// @Summary Get account by ID
// @Description Returns account details for the given ID.
// @Tags accounts
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Param filter query string false "Optional search filter"
// @Success 200 {object} model.Account
// @Success 204 "No content"
// @Failure 400 {object} api.ErrorResponse
// @Failure 404 {object} api.ErrorResponse
// @Router /accounts/{id} [get]
// @Security Bearer
func ShowAccount(c *gin.Context) {}

@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.

Copy & paste — that's it
// Bearer / JWT
// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization

// API key in header
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key

// Basic auth
// @securityDefinitions.basic BasicAuth

// OAuth2 authorization code
// @securityDefinitions.oauth2.authorizationCode OAuth2
// @authorizationUrl https://example.com/oauth/authorize
// @tokenUrl https://example.com/oauth/token
// @scope.read Read access
// @scope.write Write access

Apply to an endpoint:

Copy & paste — that's it
// @Security Bearer
// @Security OAuth2[read, write]
// @Security BasicAuth && ApiKeyAuth // AND — both required

Struct Tags

Enrich models without changing their Go type:

Copy & paste — that's it
type CreateUserRequest struct {
 Name string `json:"name" example:"Jane Doe" minLength:"2" maxLength:"100"`
 Role string `json:"role" enums:"admin,user,guest" example:"user"`
 Age int `json:"age" minimum:"18" maximum:"120"`
 Avatar []byte `json:"avatar" swaggertype:"string" format:"base64"`
 Secret string `json:"-" swaggerignore:"true"` // excluded from docs
}

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"

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. Context7 can help as a discoverability platform. For Go package docs, versions, symbols, and known vulnerabilities, → See samber/cc-skills-golang@golang-pkg-go-dev skill.

If you encounter a bug or unexpected behavior in swag, open an issue at https://github.com/swaggo/swag/issues.