121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# swag CLI Reference
|
|
|
|
## 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 |
|