Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-swagger

golang-gin-swagger

Verified

Swagger/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.

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).
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall