go-swagger3-docs

name	go-swagger3-docs
description	Documents existing Go HTTP APIs with go-swagger3 godoc @ annotations and struct tags, then generates OpenAPI 3 specs. Use when the user asks to document an API, add Swagger/OpenAPI comments, generate oas.json/yml, or mentions go-swagger3.

go-swagger3 — document existing Go APIs

Copy this file into a consumer project as .claude/skills/go-swagger3-docs/SKILL.md.

Annotate existing Go code with go-swagger3 godoc @ tags and struct tags, then run the CLI. Prefer editing comments and tags over rewriting handlers.

Install

go install github.com/parvez3019/go-swagger3@latest
export PATH="$HOME/go/bin:$PATH"

# Docker alternative
docker run -t --rm -v $(pwd):/app -w /app parvez3019/go-swagger3:latest \
  --module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg

Workflow

1. Confirm go.mod exists (Go modules only).
2. Put service annotations on the main/entry file (@Title and @Version required).
3. Annotate each HTTP handler’s godoc (comments must sit directly above the func).
4. Add json + OAS tags on request/response structs; add @Enum / @HeaderParameters types when needed.
5. Generate (pick the matching layout):

   # main next to go.mod
   go-swagger3 --module-path . --output oas.json --schema-without-pkg
   
   # main elsewhere
   go-swagger3 --module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg
   
   # only scan handlers under a path
   go-swagger3 --module-path . --main-file-path ./cmd/api/main.go --handler-path ./internal/handlers --output oas.json --schema-without-pkg
   
   # YAML
   go-swagger3 --module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg --generate-yaml
   

6. Open the output, fix gaps, re-run with --debug if needed. Use --strict when hardening.

CLI flags

Flag	Purpose
--module-path	Module root to scan
--main-file-path	File with service-level annotations
--handler-path	Optional: only scan handlers under this path
--output	Output path (default oas.json)
--schema-without-pkg	Schema names without package prefix
--generate-yaml	Emit YAML (.json output becomes .yml)
--exclude	Comma-separated dirs to skip
--quiet	Reduce log noise
--debug	Debug logging
--strict	Treat parse warnings as fatal

Also: go-swagger3 fmt -d ./ formats @ annotations.

Framework UI

Serve UI via github.com/parvez3019/go-swagger3/swagger (net/http) or adapters under swagger/gin, swagger/echo, swagger/chi, swagger/mux, swagger/fiber, swagger/hertz, swagger/buffalo, swagger/flamingo, swagger/atreugo. See docs/MIGRATION_FROM_SWAG.md and examples/.

Extra operation annotations

• @Accept / @Produce (MIME aliases: json, xml, mpfd, …)
• Per-handler @Security, @deprecated, @externalDocs.description / .url
• @Param attributes: Enums(), default(), minimum(), Format(), style(), explode(), …
• Generics: PaginatedResult[User]; composition: JSONResult{data=Order}

Patterns

Service (main file)

package main

// @Title User API
// @Version 1.0
// @Description User and restaurants API
// @ContactName API Support
// @ContactEmail [e-mail]
// @TermsOfServiceUrl https://example.com/tos
// @Server localhost:8080 Server 1
// @Server localhost:8081 Server 2
// @Security AuthorizationHeader read write
// @SecurityScheme AuthorizationHeader http bearer Input your token
// @LicenseName MIT
// @LicenseURL https://en.wikipedia.org/wiki/MIT_License
func main() {}

Shared headers

// Headers shared request headers
// @HeaderParameters Headers
type Headers struct {
	Authorization string `json:"Authorization" example:"Bearer <token>" skip:"true"`
	Version       string `json:"Client-Version" description:"Client Version"`
	Language      string `json:"Client-Language" $ref:"LanguageEnum"`
	Platform      string `json:"Client-Platform" example:"android" description:"Available values : android, ios, web"`
}

// @Enum LanguageEnum
type LanguageEnum struct {
	LanguageEnum string `enum:"en-in,en-id,id,en-mx,es-mx" example:"en-in"`
}

Handler operations

Prefer @Router and {object} / {array}. Both @Route/@Router and object/{object} work. Case-insensitive. @Tag aliases @Resource.

@Param shape: @Param {name} {in} {goType} {required} "{desc}" ["{example}"]
in: path, query, form, header, cookie, body, file
required: true, false, required, optional
Descriptions and examples must be quoted.

POST body

// @Title Create User
// @Description Creates and returns a user
// @Header model.Headers
// @Param request body model.CreateUserRequest true "Create User Request"
// @Success 200 {object} model.CreateUserResponse
// @Failure 400 {object} model.ErrorResponse
// @OperationId CreateUser
// @Resource users
// @Router /user [post]
func CreateUser() {}

GET with query + nested filter

// @Title Get restaurants list
// @Description Returns restaurants by filter
// @Header model.Headers
// @Param count query int32 false "count of restaurants"
// @Param offset query int32 false "offset" "100"
// @Param order_by query model.OrderByEnum false "order list"
// @Param filter query model.Filter false "In json format"
// @Success 200 {object} model.GetRestaurantsResponse
// @Failure 500 {object} model.ErrorResponse
// @OperationId GetRestaurants
// @Router /restaurants [get]
func GetRestaurants() {}

Path params + array response

// @Title Get user list of a group
// @Description Get users related to a specific group
// @Param groupID path int true "Id of a specific group" "120"
// @Success 200 {array} model.User "Users JSON"
// @Failure 400 {object} model.ErrorResponse "Error JSON"
// @Resource users
// @Router /api/group/{groupID}/users [get]
func GetGroupUsers() {}

PUT / PATCH / DELETE

// @Title Update User
// @Param userID path string true "User id"
// @Param request body model.UpdateUserRequest true "Update payload"
// @Success 200 {object} model.User
// @Failure 404 {object} model.ErrorResponse
// @OperationId UpdateUser
// @Router /user/{userID} [put]
func UpdateUser() {}

// @Title Delete User
// @Param userID path string true "User id"
// @Success 204 "No Content"
// @Failure 404 {object} model.ErrorResponse
// @OperationId DeleteUser
// @Router /user/{userID} [delete]
func DeleteUser() {}

File upload, cookie, header param

// @Title Upload avatar
// @Param userID path string true "User id"
// @Param file file ignored true "Avatar image"
// @Success 201 {object} model.UploadResponse
// @Router /user/{userID}/avatar [post]
func UploadAvatar() {}

// @Title Session info
// @Param session_id cookie string true "Session cookie"
// @Param X-Request-Id header string false "Client request id"
// @Success 200 {object} model.Session
// @Router /session [get]
func GetSession() {}

Status-only / string response / response headers

// @Success 200 "live endpoint"
// @Router /live [get]
func Live() {}

// @Success 201 {string} string "created id"
// @Router /updates [post]
func CreateUpdate() {}

// @Success 200 {object} model.TokenResponse "Login successful"
// @ResponseHeader 200 Set-Cookie string "Access token cookie" "accessToken=...; Path=/; HttpOnly"
// @ResponseHeader 200 X-Request-Id string "Unique request identifier"
// @Router /login [post]
func Login() {}

Models, enums, field tags

// @Enum OrderByEnum
type OrderByEnum struct {
	OrderByEnum string `enum:"nearest,popular,new,highest-rated" example:"popular"`
}

type CreateUserRequest struct {
	FirstName string   `json:"first_name" readOnly:"true"`
	LastName  string   `json:"last_name" example:"Hassan" description:"Last name"`
	Age       int      `json:"age" minimum:"18" exclusiveMinimum:"true" maximum:"256" exclusiveMaximum:"true"`
	EmailID   string   `json:"email_id" pattern:"[\\w.]+@[\\w.]"`
	UserName  string   `json:"user_name" title:"login"`
	Password  string   `json:"password" minLength:"6" maxLength:"200"`
	Roles     []string `json:"roles" writeOnly:"true" nullable:"true" uniqueItems:"true" minItems:"1" maxItems:"100"`
	Country   string   `json:"country" $ref:"CountriesEnum"`
	Version   string   `json:"version" override-example:"11.0.0"`
}

type CreateUserResponse struct {
	UserID string `json:"user_id" example:"u_123"`
}

type GetRestaurantsResponse struct {
	Restaurants []Restaurant `json:"restaurants" maxProperties:"100" minProperties:"2" additionalProperties:"true"`
}

type ErrorResponse struct {
	Code string `json:"code"`
	Msg  string `json:"msg" skip:"true"` // omitted from schema
	Secret string `json:"-"`             // hidden
}

// @Enum CountriesEnum
type CountriesEnum struct {
	CountriesEnum string `enum:"india,china,mexico,japan" example:"india"`
}

Useful tags: example, description, title, required, nullable, readOnly, writeOnly, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, pattern, minItems, maxItems, uniqueItems, minProperties, maxProperties, additionalProperties, enum, $ref, override-example, skip:"true". Hide with json:"-" or go-swagger3:"-".

Security (global only)

// HTTP bearer / basic
// @SecurityScheme AuthorizationHeader http bearer Input your token
// @SecurityScheme BasicAuth http basic Login with admin credentials

// API key
// @SecurityScheme ApiKeyAuth apiKey header X-MyCustomHeader

// OpenID Connect
// @SecurityScheme OidcAuth openIdConnect https://example.com/.well-known/openid-configuration

// OAuth2 + scopes
// @SecurityScheme MyApiAuth oauth2AuthCode /oauth/authorize /oauth/token
// @SecurityScope MyApiAuth read_user Read a user
// @SecurityScope MyApiAuth write_user Write a user
// @Security MyApiAuth read_user write_user

Also: oauth2Implicit, oauth2ResourceOwnerCredentials, oauth2ClientCredentials. Security applies to the entire service — not per operation.

End-to-end example (minimal API)

// main.go
// @Title Demo API
// @Version 1.0
// @Server http://localhost:8080 Local
func main() {}

// handler
// @Title List items
// @Param limit query int false "page size" "20"
// @Success 200 {array} Item
// @Failure 500 {object} ErrorResponse
// @OperationId ListItems
// @Router /items [get]
func ListItems() {}

type Item struct {
	ID   string `json:"id" example:"1"`
	Name string `json:"name" example:"Widget"`
}
type ErrorResponse struct {
	Message string `json:"message"`
}

Troubleshooting (for agents)

Work top-down. After each fix, re-run the CLI.

Symptom	Likely cause	What to do
command not found: go-swagger3	Binary not on PATH	export PATH="$HOME/go/bin:$PATH" or use Docker
Empty / missing info.title or info.version	Service comments not on --main-file-path	Move @Title/@Version to the main file; pass --main-file-path explicitly
No paths in output	Handlers lack @Router/@Route, or --handler-path excludes them	Add @Router /path [method]; widen or drop --handler-path
Handler present but operation missing	Comments not on the func godoc, or package outside module	Put // @... directly above func; keep handlers inside the module
Schema / type missing or wrong	Wrong package-qualified name, or type not imported/reachable	Use pkg.Type as in Go; ensure the type is in-module or a scanned dependency
Schema names look like handler.User	Package prefix included	Pass --schema-without-pkg
operation ID 'X' is not unique	Duplicate @OperationId	Make each @OperationId unique across the module
Parse warnings / --strict fails	Malformed @Param/@Success (missing quotes, bad in, bad status)	Match examples; quote descriptions; valid in values only
Field missing from schema	skip:"true", json:"-", or go-swagger3:"-"	Remove skip/hide tags if the field should appear
Nested / anonymous field wrong	Anonymous embedded structs unsupported	Give the field an explicit named type
Security missing on one route	Per-operation security not supported	Define @Security / @SecurityScheme on the service file only
Unknown tags ignored (e.g. @Accept)	Not a go-swagger3 annotation	Use only supported tags listed above
YAML not produced	Forgot flag or wrong extension expectation	Pass --generate-yaml (tool rewrites .json → .yml)
Still stuck	Need parser detail	Re-run with --debug and fix the first real error

Rules

• Do not invent unsupported annotations (@Accept, swag-only tags, etc.).
• Do not claim per-operation security.
• Anonymous struct fields are not supported.
• Go modules only.
• Prefer godoc/tag edits over handler rewrites unless asked.
• Keep @OperationId values unique.