samber/cc-skills-golang / skills/golang-swagger
golang-swagger
VerifiedGolang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, @Success, @Router, @Security), swag init code generation, framework integrations (gin, echo, fiber, chi, net/http), security definitions (Bearer/JWT, OAuth2, API key), and struct tags (swaggertype, enums, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger, github.com/swaggo/echo-swagger, github.com/swaggo/http-swagger, or github.com/swaggo/files.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| evals/evals.json | config | 10.6 KB |
| references/swag-cli.md | markdown | 5.0 KB |
references/swag-cli.md
View on GitHub# swag CLI Reference
## Table of Contents
- [swag init — Generate Documentation](#swag-init--generate-documentation)
- [swag fmt — Format Annotations](#swag-fmt--format-annotations)
- [Framework Integration Packages](#framework-integration-packages)
- [Dynamic Configuration](#dynamic-configuration)
- [Generics (swag v2)](#generics-swag-v2)
- [Nested Composition](#nested-composition)
- [Response Headers](#response-headers)
- [Function-Scoped Structs](#function-scoped-structs)
- [MIME Type Aliases](#mime-type-aliases)
## swag init — Generate Documentation
```bash
swag init # parse main.go, generate docs/
swag init -g cmd/api/main.go # general info in a different file
swag init -d ./handlers,./models # additional directories to parse
swag init --exclude ./vendor,./internal/gen # skip directories
swag init -ot go,json # output only Go and JSON (skip YAML)
swag init -q # quiet mode (no log output)
swag init --parseInternal # include internal/ packages
swag init --parseDependency # parse vendor/module dependencies
swag init --requiredByDefault # mark all struct fields as required
swag init -p camelcase # property naming: snakecase | camelcase | pascalcase
swag init --tags Users,Products # only generate for these tags
swag init --tags '!Internal' # exclude tag (! prefix)
swag init --td "[[,]]" # custom template delimiters
```
## swag fmt — Format Annotations
```bash
swag fmt # format all annotation comments
swag fmt -d ./handlers # format specific directory
swag fmt --exclude ./vendor # skip directories
```
`swag fmt` requires a standard Go doc comment (`// FuncName godoc`) immediately before the first `@` annotation — without it the formatter cannot determine indentation.
## Framework Integration Packages
| Framework | Package |
| ------------------------ | ----------------------------------- |
| Gin | `github.com/swaggo/gin-swagger` |
| Echo | `github.com/swaggo/echo-swagger` |
| Fiber | `github.com/swaggo/fiber-swagger` |
| Chi / net/http / Gorilla | `github.com/swaggo/http-swagger` |
| Buffalo | `github.com/swaggo/buffalo-swagger` |
| Hertz | `github.com/hertz-contrib/swagger` |
The shared files package (`github.com/swaggo/files`) is required by all integrations.
## Dynamic Configuration
Override spec values at runtime — useful for multi-environment deployments where host and basepath differ between staging and production:
```go
import docs "yourmodule/docs" // named import required to access docs.SwaggerInfo
func main() {
docs.SwaggerInfo.Title = "My API"
docs.SwaggerInfo.Description = "Production API"
docs.SwaggerInfo.Version = "2.0"
docs.SwaggerInfo.Host = os.Getenv("API_HOST")
docs.SwaggerInfo.BasePath = "/api/v1"
docs.SwaggerInfo.Schemes = []string{"https"}
}
```
## Generics (swag v2)
Single type parameter:
```go
// @Success 200 {object} api.Response[model.User]
// @Success 200 {array} api.Response[model.User]
```
Multiple type parameters:
```go
// @Success 200 {object} api.Response[model.User, model.Meta]
```
## Nested Composition
Embed or override fields in the documented schema without changing Go types:
```go
// @Success 200 {object} api.Envelope{data=model.User}
// @Success 200 {object} api.Envelope{data=[]model.User}
// @Success 200 {object} api.Envelope{data=model.User,meta=api.Pagination}
```
## Response Headers
```go
// @Header 200 {string} X-Request-ID "Unique request identifier"
// @Header 200,400 {string} X-Request-ID "Unique request identifier"
// @Header all {string} X-Request-ID "Present on every response"
```
## Function-Scoped Structs
swag can parse structs defined inside handler functions:
```go
// @Param req body main.CreateUser.request true "Create user input"
func CreateUser(c *gin.Context) {
type request struct {
Name string `json:"name"`
Email string `json:"email"`
}
}
```
## MIME Type Aliases
| Alias | Content-Type |
| ----------------------- | --------------------------------- |
| `json` | application/json |
| `xml` | application/xml |
| `plain` | text/plain |
| `html` | text/html |
| `mpfd` | multipart/form-data |
| `x-www-form-urlencoded` | application/x-www-form-urlencoded |
| `octet-stream` | application/octet-stream |
| `png` / `jpeg` / `gif` | image/png, image/jpeg, image/gif |
| `event-stream` | text/event-stream |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |