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-responses.md
View on GitHub# Swagger Annotations — Response Patterns
All response annotation patterns: single object, array, paginated, no-content, primitives, failures, grouped codes, and response headers.
## Syntax
`@Success <code> {<type>} <model> "<description>"`
## Single Object and Array
```go
// @Success 200 {object} domain.User "OK"
// @Success 201 {object} domain.User "Created"
// @Success 200 {array} domain.User "List of users"
```
## Paginated Response
Define a wrapper struct for pagination:
```go
type PaginatedResponse struct {
Data []domain.User `json:"data"`
Page int `json:"page" example:"1"`
Limit int `json:"limit" example:"20"`
TotalCount int `json:"total_count" example:"150"`
TotalPages int `json:"total_pages" example:"8"`
}
// @Success 200 {object} PaginatedResponse "Paginated list"
```
## No Content and Primitives
```go
// @Success 204 "No content"
// @Success 200 {string} string "Plain text response"
// @Success 200 {integer} int "Count"
// @Success 200 {boolean} bool "Status"
```
## Failure Responses
Document all possible error codes:
```go
// @Failure 400 {object} domain.ErrorResponse "Bad request"
// @Failure 401 {object} domain.ErrorResponse "Unauthorized"
// @Failure 403 {object} domain.ErrorResponse "Forbidden"
// @Failure 404 {object} domain.ErrorResponse "Not found"
// @Failure 409 {object} domain.ErrorResponse "Conflict"
// @Failure 422 {object} domain.ErrorResponse "Validation failed"
// @Failure 429 {object} domain.ErrorResponse "Rate limit exceeded"
// @Failure 500 {object} domain.ErrorResponse "Internal server error"
```
## Grouped Failure Codes
When multiple codes share the same response type:
```go
// @Failure 400,401,404,500 {object} domain.ErrorResponse
```
## Response Headers
Document headers returned with responses:
```go
// @Success 200 {object} domain.User
// @Header 200 {string} X-Request-ID "Unique request identifier"
// @Header 200 {integer} X-RateLimit-Remaining "Remaining requests"
// @Header 200 {string} X-RateLimit-Reset "Reset timestamp"
```
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 |