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-crud-auth.md
View on GitHub# Swagger Annotations — CRUD Handlers and Auth Endpoints
Complete annotations for CRUD operations (Update, Patch, Delete) and auth endpoints (Register, Login, Refresh).
## CRUD Handler Annotations
### Update (PUT)
```go
// Update godoc
//
// @Summary Update user
// @Description Replace all user fields
// @Tags users
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path string true "User ID" format(uuid)
// @Param input body domain.UpdateUserRequest true "Fields to update"
// @Success 200 {object} domain.UserResponse
// @Failure 400 {object} domain.ErrorResponse
// @Failure 401 {object} domain.ErrorResponse
// @Failure 404 {object} domain.ErrorResponse
// @Failure 500 {object} domain.ErrorResponse
// @Router /users/{id} [put]
func (h *UserHandler) Update(c *gin.Context) {}
```
### Patch (PATCH)
```go
// Patch godoc
//
// @Summary Partially update user
// @Description Update only the provided fields; omitted fields are unchanged
// @Tags users
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path string true "User ID" format(uuid)
// @Param input body domain.PatchUserRequest true "Fields to patch"
// @Success 200 {object} domain.UserResponse
// @Failure 400 {object} domain.ErrorResponse
// @Failure 401 {object} domain.ErrorResponse
// @Failure 404 {object} domain.ErrorResponse
// @Failure 500 {object} domain.ErrorResponse
// @Router /users/{id} [patch]
func (h *UserHandler) Patch(c *gin.Context) {}
```
### Delete
```go
// Delete godoc
//
// @Summary Delete user
// @Description Permanently remove a user account
// @Tags users
// @Security BearerAuth
// @Param id path string true "User ID" format(uuid)
// @Success 204
// @Failure 401 {object} domain.ErrorResponse
// @Failure 403 {object} domain.ErrorResponse
// @Failure 404 {object} domain.ErrorResponse
// @Failure 500 {object} domain.ErrorResponse
// @Router /users/{id} [delete]
func (h *UserHandler) Delete(c *gin.Context) {}
```
## Auth Endpoint Annotations
These do not require `@Security` — they produce tokens, not consume them.
### Register
```go
// Register godoc
//
// @Summary Register a new account
// @Description Create a user account and return access + refresh tokens
// @Tags auth
// @Accept json
// @Produce json
// @Param request body domain.RegisterRequest true "Registration payload"
// @Success 201 {object} domain.TokenResponse
// @Failure 400 {object} domain.ErrorResponse
// @Failure 409 {object} domain.ErrorResponse "Email already registered"
// @Failure 500 {object} domain.ErrorResponse
// @Router /auth/register [post]
func (h *AuthHandler) Register(c *gin.Context) {}
```
### Login
```go
// Login godoc
//
// @Summary Log in
// @Description Authenticate with email and password; returns access + refresh tokens
// @Tags auth
// @Accept json
// @Produce json
// @Param request body domain.LoginRequest true "Login credentials"
// @Success 200 {object} domain.TokenResponse
// @Failure 400 {object} domain.ErrorResponse
// @Failure 401 {object} domain.ErrorResponse "Invalid credentials"
// @Failure 500 {object} domain.ErrorResponse
// @Router /auth/login [post]
func (h *AuthHandler) Login(c *gin.Context) {}
```
### Refresh Token
```go
// RefreshToken godoc
//
// @Summary Refresh access token
// @Description Exchange a valid refresh token for a new access token
// @Tags auth
// @Accept json
// @Produce json
// @Param request body domain.RefreshRequest true "Refresh token payload"
// @Success 200 {object} domain.TokenResponse
// @Failure 400 {object} domain.ErrorResponse
// @Failure 401 {object} domain.ErrorResponse "Refresh token expired or invalid"
// @Failure 500 {object} domain.ErrorResponse
// @Router /auth/refresh [post]
func (h *AuthHandler) RefreshToken(c *gin.Context) {}
```
### Supporting Auth DTOs
```go
// domain/auth.go
type RegisterRequest struct {
Name string `json:"name" example:"Jane Doe" binding:"required,min=2,max=100"`
Email string `json:"email" example:"jane@example.com" binding:"required,email"`
Password string `json:"password" example:"s3cur3P@ss!" binding:"required,min=8"`
}
type LoginRequest struct {
Email string `json:"email" example:"jane@example.com" binding:"required,email"`
Password string `json:"password" example:"s3cur3P@ss!" binding:"required"`
}
type RefreshRequest struct {
RefreshToken string `json:"refresh_token" example:"eyJhbGci..." binding:"required"`
}
type TokenResponse struct {
AccessToken string `json:"access_token" example:"eyJhbGci..."`
RefreshToken string `json:"refresh_token" example:"eyJhbGci..."`
ExpiresIn int `json:"expires_in" example:"3600"`
}
```
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 |