Skip to content

samber/cc-skills-golang / skills/golang-swagger

golang-swagger

Verified

Golang 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.

FileKindSize
SKILL.mdskill md9.1 KB
evals/evals.jsonconfig10.6 KB
references/swag-cli.mdmarkdown5.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                 |
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall