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-extras.md

View on GitHub
# Swagger Annotations — File Uploads, Model Renaming, Deprecation, and Extensions

File upload annotations, model renaming, deprecating endpoints, tag metadata, and custom extensions.

## File Uploads

### Single File

```go
// UploadAvatar godoc
//
// @Summary      Upload user avatar
// @Tags         users
// @Accept       multipart/form-data
// @Produce      json
// @Security     BearerAuth
// @Param        id    path      string  true  "User ID"
// @Param        file  formData  file    true  "Avatar image"
// @Success      200   {object}  domain.UploadResponse
// @Failure      400   {object}  domain.ErrorResponse
// @Router       /users/{id}/avatar [post]
func (h *UserHandler) UploadAvatar(c *gin.Context) { ... }
```

### Multiple Files and Mixed Form

```go
// Multiple files
// @Param  files  formData  file  true  "Upload files"  collection(multi)

// File + form fields
// @Accept  multipart/form-data
// @Param   name   formData  string  true  "Document name"
// @Param   file   formData  file    true  "Document file"
```

## Model Renaming

Override the model name in Swagger output (useful for disambiguating types with the same name across packages):

```go
// UserResponse is the public representation of a user.
//
// @name UserResponse
type User struct {
    ID    string `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}
```

In generated docs, this appears as `UserResponse` instead of `domain.User`.

## Deprecating Endpoints

```go
// GetUserV1 godoc
//
// @Summary      Get user (deprecated)
// @Description  Use GET /api/v2/users/{id} instead
// @Deprecated
// @Tags         users
// @Router       /users/{id} [get]
func (h *UserHandler) GetUserV1(c *gin.Context) { ... }
```

The endpoint appears with a strikethrough in Swagger UI.

## Tag Metadata

Add descriptions to tags in the Swagger UI sidebar (place in the general API info block):

```go
// @tag.name         users
// @tag.description  Operations on user accounts

// @tag.name         auth
// @tag.description  Authentication and token management

// @tag.name         admin
// @tag.description  Administrative operations (requires admin role)
```

## Custom Extensions

Use `@x-` prefix for vendor-specific or custom metadata. Values are JSON:

```go
// General API extensions
// @x-logo  {"url": "https://example.com/logo.png", "altText": "API Logo"}

// Operation-level extensions
// ListUsers godoc
//
// @Summary        List users
// @x-codeSamples  [{"lang": "curl", "source": "curl -H 'Authorization: Bearer {token}' https://api.example.com/users"}]
// @Router         /users [get]

// Field-level extensions
type User struct {
    Role string `json:"role" x-order:"1"`
}
```

Custom extensions appear in the raw `swagger.json` output and are consumed by tools that understand them (e.g., Redoc uses `x-logo`, `x-codeSamples`).
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