swagger-docs

name

swagger-docs

description

Documents Spazio Backend REST API endpoints with Swagger/OpenAPI annotations for Go + Gin. Use this skill whenever the user asks to document a handler, add Swagger annotations, write @Summary/@Param/@Success comments for Gin, generate module documentation, or update the OpenAPI contract for any backend endpoint. Also applies when swaggo, gin-swagger, swag generate, or any task related to keeping documentation in sync with code changes is mentioned.

Spazio Swagger Docs Skill

Generates and maintains industry-standard Swagger/OpenAPI annotations for the Spazio backend (Go + Gin + pgx + swaggo).

All documentation must be written in English — summaries, descriptions, param descriptions, struct comments, and field examples.

Project Context

• Stack: Go, Gin, pgx v5, swaggo/swag
• Architecture: Vertical slices per domain module
• Active modules: properties, services, catalogs, clauses, locations
• Each module contains: handler.go, service.go, repository.go, model.go, module.go
• Responses: always JSON
• Base path: /
• Local host: localhost:8080

---

Before Writing Anything

Read the module's model.go and handler.go first. Check model.go for request/response structs, and handler.go for registered routes, validations, and HTTP status codes used. Only look at repository.go if the contract is unclear.

---

Annotation Format

Place the godoc block immediately above the handler function:

// FunctionName godoc
// @Summary      Short imperative title (≤10 words)
// @Description  Full description of behavior, including relevant business rules
// @Tags         ModuleName
// @Accept       json
// @Produce      json
// @Param        id       path     int                 true  "Resource ID"
// @Param        request  body     CreateXxxRequest    true  "Creation payload"
// @Success      200      {object} XxxResponse               "Resource found"
// @Success      201      {object} XxxResponse               "Resource created"
// @Failure      400      {object} shared.ErrorResponse      "Invalid input"
// @Failure      404      {object} shared.ErrorResponse      "Not found"
// @Failure      500      {object} shared.ErrorResponse      "Internal error"
// @Router       /route/{id} [get]
func (h *Handler) FunctionName(c *gin.Context) {

Module Tags

Module	Swagger Tag	Route prefix
properties	Properties	/properties
services	Services	/services
catalogs	Catalogs	/catalogs
clauses	Clauses	/clauses
locations	Locations	/locations

---

Model Structs

Define request/response structs in model.go with json tags and example annotations. Swaggo uses these to generate sample values in Swagger UI.

// CreatePropertyRequest holds the data needed to register a new property.
type CreatePropertyRequest struct {
    Title       string  `json:"title"        example:"Apartment in Xalapa"`
    Description string  `json:"description"  example:"Spacious apartment with park view"`
    Price       float64 `json:"price"        example:"3500.00"`
    TypeID      int     `json:"type_id"      example:"1"`
}

// PropertyResponse represents a serialized property for the client.
type PropertyResponse struct {
    ID        int     `json:"id"         example:"42"`
    Title     string  `json:"title"      example:"Apartment in Xalapa"`
    Price     float64 `json:"price"      example:"3500.00"`
    CreatedAt string  `json:"created_at" example:"2025-01-15T10:00:00Z"`
}

Keep Request and Response structs clearly separated. Mark optional fields with omitempty and set their @Param as false.

---

Shared Error Response

internal/shared/ must have this struct (create it if missing):

// ErrorResponse is the standard error structure for API responses.
type ErrorResponse struct {
    Code    int    `json:"code"    example:"404"`
    Message string `json:"message" example:"Resource not found"`
}

Reference it as shared.ErrorResponse in all @Failure annotations.

---

Parameter Reference

// Path param
// @Param id path int true "Property ID"

// Optional query params
// @Param page  query int false "Page number"           default(1)
// @Param limit query int false "Results per page"      default(20)

// Request body
// @Param request body CreateXxxRequest true "Resource payload"

// Auth header (if applicable)
// @Param Authorization header string true "Bearer {token}"

---

Global Annotations (main.go)

// @title           Spazio API
// @version         1.0
// @description     REST API for real estate management — properties, clients, operations, and payments.
// @contact.name    Spazio Team
// @license.name    Proprietary
// @host            localhost:8080
// @BasePath        /
// @schemes         http https

---

Regenerating Docs

After adding or modifying annotations, remind the user to regenerate:

swag init -g cmd/api/main.go --output docs
# or, if the entry point is at the root:
swag init -g main.go --output docs

---

Endpoint Quality Checklist

• @Summary is ≤10 words, imperative ("Get property by ID", not "This endpoint gets...")
• @Description covers behavior and any relevant business rules
• Each @Param has: name, location, type, required/optional, description
• @Success uses the correct HTTP code (200 for GET/PUT, 201 for POST, 204 for DELETE with no body)
• @Failure covers at least 400, 404 (when applicable), and 500
• @Router matches the registered route exactly (including leading / and {id} params)
• Referenced structs exist in model.go with example tags
• Module tag is consistent with the naming table above
• @Accept json is only included when the endpoint receives a request body — omit it on GET endpoints
• @Failure 400 is only included when the endpoint parses params or a body — pure list endpoints that cannot produce a 400 must omit it
• @Description field names are plain text — do not wrap them in backticks, swaggo renders them as literals

---

Go ↔ Swagger Type Reference

Go type	Swagger type
int	integer
float64	number
string	string
bool	boolean
time.Time	string
[]XxxType	array
struct	object

For arrays: {array} []PropertyResponse

---

Reference Files

• references/pagination.md — Standard pattern for paginated endpoints
• references/domain-entities.md — Domain entity summary for business context

Read these when the endpoint involves pagination or when domain context is needed.