القائمة
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.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | golang-gin-swagger |
| description | 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. |
| license | MIT |
| metadata | {"author":"henriqueatila","version":"1.0.3"} |
Generate and serve Swagger/OpenAPI documentation for Gin APIs using swaggo/swag. This skill covers the 80% you need daily: setup, handler annotations, model tags, Swagger UI, and doc generation.
swagger.json/swagger.yaml from Go annotationsDependencies
go install github.com/swaggo/swag/cmd/swag@latest — CLI doc generatorgo get -u github.com/swaggo/gin-swagger + go get -u github.com/swaggo/files$(go env GOPATH)/bin is in $PATHGeneral API Annotations
main() in cmd/api/main.go — one block per project@host, @BasePath, @schemes, and @securityDefinitions.apikey BearerAuthServing Swagger UI
_ "myapp/docs" is required — without it, spec is never registeredos.Getenv("GIN_MODE") != "release" to hide from productionhttp://localhost:8080/swagger/index.htmlHandler Annotations — Critical Rules
@Router uses {id} (OpenAPI style), NOT :id (Gin style)@Security BearerAuth must match @securityDefinitions.apikey name exactly@Success/@Failure — never gin.H{} or map[string]interface{}// FuncName godoc)Key Struct Tags for swag
| Tag | Purpose | Example |
|---|---|---|
example:"..." | Sample value in Swagger UI | example:"jane@example.com" |
format:"..." | OpenAPI format | format:"uuid", format:"email", format:"date-time" |
enums:"a,b" | Allowed values | enums:"admin,user" |
swaggerignore:"true" | Exclude field from docs | Hide PasswordHash |
swaggertype:"string" | Override inferred type | For time.Time, sql.NullInt64 |
minimum: / maximum: | Numeric bounds | minimum:"1" maximum:"100" |
minLength: / maxLength: | String length bounds | minLength:"2" maxLength:"100" |
default:"..." | Default value | default:"20" |
Generating Docs
swag fmt && swag init -g cmd/api/main.go — format then generateswag init -g cmd/api/main.go -d ./,./internal/handler,./internal/domainswag init -g cmd/api/main.go --parseInternal — for types in internal/docs/ directory; re-run after every handler or model changeCommon Gotchas
| Gotcha | Fix |
|---|---|
swag CLI not found | Add $(go env GOPATH)/bin to $PATH |
| Docs not updating | Re-run swag init — no watch mode |
Blank import _ "myapp/docs" missing | Swagger UI shows empty |
@Router uses :id instead of {id} | Use {id} in annotations |
@Security name mismatch | Must match @securityDefinitions.apikey name exactly |
time.Time rendered as object | Add swaggertype:"string" format:"date-time" |
| Type not found during parsing | Add --parseInternal or --parseDependency |
map[string]interface{} in response | Replace with a named struct |
internal_ prefix on model names | Known bug — use --useStructName |
swag init with the same flags, read the error word-for-word, check if the issue is a missing import, wrong path, or type in a different package@Security on protected routes? examples realistic? swag fmt ran? Am I personally satisfied?This skill handles Swagger/OpenAPI documentation for Go Gin APIs using swaggo/swag: handler annotations, model tags, Swagger UI setup, doc generation, and CI/CD validation. Does NOT handle API implementation (see golang-gin-api), authentication (see golang-gin-auth), database (see golang-gin-database), or deployment (see golang-gin-deploy).
Load these when you need deeper detail:
@securityDefinitions.apikey BearerAuth: see the golang-gin-auth skillswag init to Docker builds: see the golang-gin-deploy skillIf this skill doesn't cover your use case, consult the swag GitHub, gin-swagger GoDoc, or Swagger 2.0 spec.
Build REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.
JWT auth and RBAC for Go Gin APIs. Use when adding login, signup, JWT tokens, role checks, protected routes, or password hashing to a Gin app.
PostgreSQL integration for Go Gin with GORM/sqlx. Use when adding a database, writing queries, creating repositories, running migrations, or wiring DB layers in a Gin project.
Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.
Deploy Go Gin APIs with Docker, docker-compose, Kubernetes. Use when Dockerizing a Go app, setting up docker-compose, deploying to K8s, or configuring CI/CD and health probes.
PostgreSQL DBA for Go Gin APIs. Use when designing schemas, analyzing migrations, choosing indexes, optimizing queries, or selecting extensions (pgvector, PostGIS, TimescaleDB).