henriqueatila/golang-gin-best-practices / skills/golang-gin-swagger
golang-gin-swagger
VerifiedSwagger/OpenAPI docs for Go Gin with swaggo/swag. Use when adding API docs, Swagger UI, endpoint annotations, or generating swagger.json for a Gin application.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| metadata.json | config | 492 B |
| references/annotations-advanced.md | markdown | 4.0 KB |
| references/annotations-crud-auth.md | markdown | 5.1 KB |
| references/annotations-extras.md | markdown | 2.8 KB |
| references/annotations-params-responses.md | markdown | 3.5 KB |
| references/annotations-responses.md | markdown | 2.2 KB |
| references/ci-cd-tooling.md | markdown | 4.6 KB |
| references/ci-cd-workflows.md | markdown | 2.7 KB |
| references/setup-models-generate.md | markdown | 3.4 KB |
| references/setup-serve.md | markdown | 2.7 KB |
references/annotations-advanced.md
View on GitHub# Swagger Annotations — Advanced Features
Security definitions, model tags, enums from constants, file uploads, model renaming, deprecation, tag metadata, and custom extensions.
## Security Definitions
### API Key (Bearer JWT)
```go
// In main.go:
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description Enter: Bearer {token}
// On each protected handler:
// @Security BearerAuth
```
### API Key (Custom Header)
```go
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key
// @description API key for service access
```
### Basic Auth and OAuth2
```go
// @securityDefinitions.basic BasicAuth
// @securityDefinitions.oauth2.implicit OAuth2Implicit
// @authorizationUrl https://auth.example.com/authorize
// @scope.read Read access
// @scope.write Write access
// @securityDefinitions.oauth2.accessCode OAuth2AccessCode
// @tokenUrl https://auth.example.com/token
// @authorizationUrl https://auth.example.com/authorize
```
### Multiple Schemes on One Endpoint
```go
// Both required (AND logic):
// @Security BearerAuth
// @Security ApiKeyAuth
// Either accepted (OR logic):
// @Security BearerAuth || ApiKeyAuth
```
## Model Tags
Complete list of struct tags recognized by swag:
```go
type Example struct {
// Value constraints
Name string `json:"name" example:"Jane" minLength:"2" maxLength:"100"`
Age int `json:"age" example:"30" minimum:"0" maximum:"150"`
Score float64 `json:"score" example:"9.5" minimum:"0" maximum:"10"`
// Format hints
ID string `json:"id" example:"550e8400-..." format:"uuid"`
Email string `json:"email" example:"j@example.com" format:"email"`
Website string `json:"website" example:"https://..." format:"uri"`
CreatedAt time.Time `json:"created_at" example:"2024-01-15T10:30:00Z" format:"date-time"`
Birthday string `json:"birthday" example:"1990-05-15" format:"date"`
// Enums
Role string `json:"role" example:"admin" enums:"admin,user,guest"`
Status string `json:"status" example:"active" enums:"active,inactive,banned"`
// Defaults
Page int `json:"page" default:"1"`
Limit int `json:"limit" default:"20"`
// Type overrides (for types swag can't infer)
UpdatedAt CustomTime `json:"updated_at" swaggertype:"string" format:"date-time"`
ExternalID sql.NullInt64 `json:"external_id" swaggertype:"integer"`
Tags []big.Float `json:"tags" swaggertype:"array,number"`
Metadata interface{} `json:"metadata" swaggertype:"object"`
// Exclusions
PasswordHash string `json:"-" swaggerignore:"true"`
InternalFlag bool `json:"internal_flag" swaggerignore:"true"`
// Read-only / Write-only
ID2 string `json:"id2" readOnly:"true"` // shown in response only
Pwd string `json:"pwd" writeOnly:"true"` // shown in request only
// Required (swag infers from binding tag)
Required string `json:"required" binding:"required"`
}
```
## Enums from Constants
Swag auto-detects Go `const` blocks and generates enum values:
```go
type OrderStatus string
const (
OrderPending OrderStatus = "pending"
OrderProcessing OrderStatus = "processing"
OrderShipped OrderStatus = "shipped"
OrderDelivered OrderStatus = "delivered"
OrderCancelled OrderStatus = "cancelled"
)
type Order struct {
ID string `json:"id"`
Status OrderStatus `json:"status"` // swagger generates enum automatically
}
```
Works when `OrderStatus` is a named type with `const` values of that type in the same package.
For file uploads, model renaming, deprecation, tag metadata, and custom extensions: see [annotations-extras.md](annotations-extras.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |