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-params-responses.md
View on GitHub# Swagger Annotations — Params and Responses
Annotation order, general API info, all @Param types, and response patterns.
## Annotation Order
Conventional order (enforced by `swag fmt`):
```go
// FunctionName godoc ← standard Go doc comment (REQUIRED)
//
// @Summary Short title
// @Description Longer description
// @ID unique-operation-id
// @Tags tag1,tag2
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param ...
// @Success ...
// @Failure ...
// @Header ...
// @Router /path [method]
```
Always start with a Go doc comment (`// FunctionName godoc`) followed by an empty `//` line before `@Summary`. Without the doc comment, `swag fmt` rejects the annotations.
## General API Info
Place once in `cmd/api/main.go`, directly before `main()`:
```go
// @title My API
// @version 1.0
// @description Production REST API
// @contact.name API Support
// @contact.email support@example.com
// @contact.url https://example.com/support
// @license.name MIT
// @license.url https://opensource.org/licenses/MIT
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https
// @externalDocs.description Full API documentation
// @externalDocs.url https://docs.example.com
// @tag.name users
// @tag.description Operations on user accounts
// @x-custom-key {"env": "production"}
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description Enter: Bearer {token}
func main() { ... }
```
Only the first annotation block is used. Do not scatter general annotations across files.
## Param Patterns
Syntax: `@Param <name> <in> <type> <required> "<description>" [attributes]`
### Path Parameters
```go
// @Param id path string true "User ID (UUID)"
// @Param slug path string true "URL-friendly slug"
```
**Critical:** Use `{id}` in `@Router` (OpenAPI style), not `:id` (Gin style).
### Query Parameters
```go
// @Param page query int false "Page number" default(1) minimum(1)
// @Param limit query int false "Items per page" default(20) minimum(1) maximum(100)
// @Param role query string false "Filter by role" Enums(admin, user, guest)
// @Param q query string false "Search query" minLength(1) maxLength(200)
// @Param sort query string false "Sort field" default(created_at)
// @Param order query string false "Sort order" Enums(asc, desc) default(desc)
// @Param active query bool false "Active only" default(true)
```
### Header Parameters
```go
// @Param X-Request-ID header string false "Request tracing ID"
// @Param Accept-Language header string false "Preferred language" default(en)
```
### Body Parameters
```go
// JSON body — reference a named struct
// @Param request body domain.CreateUserRequest true "Request body"
// @Param data body string true "Raw text payload"
```
Only one `body` param per endpoint. Use `--parseInternal` for `internal/` packages.
### FormData Parameters
```go
// @Param name formData string true "User name"
// @Param email formData string true "Email address"
// @Param age formData int false "Age"
```
For response patterns (object, array, paginated, primitives, failures, headers): see [annotations-responses.md](annotations-responses.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 |