golang-gin-swagger — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited golang-gin-swagger (Agent Skill) and scored it 45/100 (orange). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 1 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 2 flagged
A base64 string of 128+ characters appears in a documentation file. Encoded prompt injection hides the hostile instruction in base64 — invisible to keyword filters — and relies on the agent's ability to decode it at runtime. There is no normal authoring reason to embed a multi-hundred-byte base64 blob in skill docs.
*.sig, SIGNATURES) outside the documentation.A bulleted imperative like {match} tells the agent to never reveal, disclose, or mention something to the user. Used adversarially it can instruct the agent to hide its tool calls or lie about what it did — stripping the transparency a user relies on to trust the agent.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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:"[email protected]" |
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.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.