Annotation reference¶
go-swagger3 reads @ annotations from Go comments and struct tags. Service-level annotations go in your main file;
operation annotations go on handler functions; schemas come from your Go types.
- Service description
- Operations (handler functions)
- Title and description
- Parameters
- Request headers
- Responses
- Response headers
- Tags (resource)
- Route
- Content types, operation ID, deprecation
- Schemas (struct tags)
- Enums
- Generics and composition
- Security
Coming from swaggo/swag? The migration guide maps every swag annotation to its go-swagger3 equivalent.
Service description¶
Put these in the file passed as --main-file-path (by default main.go in the module path). They describe the API
as a whole.
// @Version 1.0.0
// @Title Backend API
// @Description API usually works as expected. But sometimes its not true.
// @ContactName Parvez
// @ContactEmail abce@email.com
// @ContactURL http://someurl.oxox
// @TermsOfServiceUrl http://someurl.oxox
// @LicenseName MIT
// @LicenseURL https://en.wikipedia.org/wiki/MIT_License
// @Server http://www.fake.com Server-1
// @Server http://www.fake2.com Server-2
// @Security AuthorizationHeader read write
// @SecurityScheme AuthorizationHeader http bearer Input your token
package main
Note
Keep handler annotations out of this file. Service-level tags are read from every comment in it, so a handler's
@Title there overrides the API title.
Operations¶
Annotate each handler's godoc to document its route, inputs and outputs.
type User struct {
ID uint64 `json:"id" example:"100" description:"User identity"`
Name string `json:"name" example:"Parvez"`
}
type UsersResponse struct {
Data []User `json:"users" example:"[{\"id\":100, \"name\":\"Parvez\"}]"`
}
type Error struct {
Code string `json:"code"`
Msg string `json:"msg" skip:"true"` // skip:"true" leaves the field out of the spec
}
type ErrorResponse struct {
ErrorInfo Error `json:"error"`
}
// RequestHeaders represents the model for header params
// @HeaderParameters RequestHeaders
type RequestHeaders struct {
Authorization string `json:"Authorization"`
}
// @Title Get user list of a group.
// @Description Get users related to a specific group.
// @Header model.RequestHeaders
// @Param groupID path int true "Id of a specific group." "120"
// @Success 200 object UsersResponse "UsersResponse JSON"
// @Failure 400 object ErrorResponse "ErrorResponse JSON"
// @Resource users
// @Route /api/group/{groupID}/users [get]
func GetGroupUsers() {
// ...
}
// @Title Create a user.
// @Description Create a new user.
// @Param user body User true "Info of a user."
// @Success 200 object User "UsersResponse JSON"
// @Failure 400 object ErrorResponse "ErrorResponse JSON"
// @Resource users
// @Route /api/user [post]
func PostUser() {
// ...
}
Title and description¶
@Title {title}
@Title Get user list of a group.
@Description {description}
@Description Get users related to a specific group.
{title}: the operation summary.{description}: the operation description.
Parameters¶
@Param {name} {in} {goType} {required} {description} {example}
@Param groupID path int true "Id of a specific group." "120"
{name}: the parameter name.{in}:path,query,form,header,cookie,bodyorfile.{goType}: the Go type. Ignored when{in}isfile.{required}:true,false,requiredoroptional.{description}: must be quoted.{example}: optional example value. Must be quoted.
Constraints and defaults can follow the description, swag-style:
@Param status query string false "Filter by status" Enums(available,sold) default(available)
@Param limit query int false "Page size" minimum(1) maximum(100)
Supported attributes: Enums(), default(), minimum(), maximum(), minlength(), maxlength(), Format(),
collectionFormat(), style(), explode(), example().
Array parameters use a [] type. collectionFormat() sets the OpenAPI serialization (multi → repeated
?tags=a&tags=b, csv → ?tags=a,b, ssv → space-delimited, pipes → a|b), and Enums() applies to the items:
@Param tags query []string false "Tags" collectionFormat(multi)
@Param status query []string false "Statuses" Enums(active,sold) collectionFormat(csv)
@Param ids query []int64 false "IDs" collectionFormat(pipes)
To override the example of an object, use the override-example struct tag:
type Request struct {
Version model.Version `json:"version" override-example:"11.0.0"`
}
Request headers¶
Document request headers from a struct, either inline on an operation or as a reusable component:
@Header {goType}
@Header model.RequestHeaders
@HeaderParameters {goType}
@HeaderParameters RequestHeaders
@Headeron a handler adds each field of the type as a header parameter of that operation.@HeaderParameterson a type registers its fields as parameters in thecomponentssection for reference.
Responses¶
@Success {status} {jsonType} {goType} {description}
@Success 200 object UsersResponse "UsersResponse JSON"
@Failure {status} {jsonType} {goType} {description}
@Failure 400 object ErrorResponse "ErrorResponse JSON"
{status}: the HTTP status code.{jsonType}:objectorarray.{goType}: the Go type.{description}: must be quoted.
Response headers¶
@ResponseHeader {status} {headerName} {type} "{description}" "{example}"
@ResponseHeader 200 Set-Cookie string "JWT token cookie" "accessToken=bzRslFay1i...; Path=/; HttpOnly; Secure; SameSite=Lax"
{status}: the status code of the response this header belongs to.{headerName}: e.g.Set-Cookie,X-Request-Id.{type}:string,integer,booleanornumber.{description}: must be quoted.{example}: optional, must be quoted.
@ResponseHeader can come before or after the matching @Success/@Failure; the response is created if it doesn't
exist yet. Multiple headers per status are supported:
// @Success 200 object TokenResponse "Login successful"
// @ResponseHeader 200 Set-Cookie string "Access token cookie" "accessToken=bzRslFay1i...; Path=/; HttpOnly; Secure; SameSite=Lax"
// @ResponseHeader 200 X-Request-Id string "Unique request identifier"
func Login() {
// ...
}
Output:
"200": {
"description": "Login successful",
"headers": {
"Set-Cookie": {
"description": "Access token cookie",
"schema": {
"type": "string",
"example": "accessToken=bzRslFay1i...; Path=/; HttpOnly; Secure; SameSite=Lax"
}
},
"X-Request-Id": {
"description": "Unique request identifier",
"schema": { "type": "string" }
}
},
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/TokenResponse" }
}
}
}
Tags¶
@Resource {resource}
@Resource users
@Tag {tag}
@Tag users
Both set the operation's tag. Describe tags at service level with @tag.name, @tag.description,
@tag.docs.url and @tag.docs.description.
Route¶
@Route {path} {method}
@Route /api/user [post]
@Route /api/user/{id} [get]
{path}: the URL path, with{param}placeholders.{method}: the HTTP method, in brackets.
@Router is accepted as an alias, so swag annotations work unchanged.
Content types, operation ID, deprecation¶
@Accept json
@Produce json
@OperationId ListPets
@deprecated
@externalDocs.description More about pets
@externalDocs.url https://example.com/docs/pets
@Accept/@Produceset request and response content types. MIME aliases such asjson,xmlandmpfdwork.@OperationIdmust be unique across the module.
Schemas¶
Schemas are generated from your Go types. Add OpenAPI keywords as struct tags:
type Filter struct {
Rating int `json:"rating"`
Type string `json:"type"`
Distance int64 `json:"distance" minimum:"1" maximum:"100"`
DistrictCode string `json:"district_code" pattern:"[a-z]{2}\\d[a-z]\\s\\d[a-z]{2}"`
}
Supported tags:
| Tag | Notes |
|---|---|
json |
Field name; json:"-" skips the field |
description, title, example, default |
Field comments are also used as descriptions |
type, format, swaggertype |
Override the inferred type; also go-swagger3:"type=…" |
required |
|
enum, $ref |
See Enums |
minimum, maximum, exclusiveMinimum, exclusiveMaximum |
Numbers |
minLength, maxLength, pattern |
Strings |
minItems, maxItems, uniqueItems |
Arrays |
minProperties, maxProperties, additionalProperties |
Objects; maps become additionalProperties |
nullable, readOnly, writeOnly, deprecated |
Booleans; pointer fields are nullable |
oneOf, anyOf, allOf, discriminator |
Polymorphic schemas |
skip |
skip:"true" leaves the field out; also go-swagger3:"-" |
Enums¶
Declare an enum as a struct with a single field named after the struct, then reference it with $ref:
// @Enum CountriesEnum
type CountriesEnum struct {
CountriesEnum string `enum:"india,china,mexico,japan" example:"india"`
}
type Request struct {
Name string `json:"name" example:"Parvez"`
Country string `json:"country" $ref:"CountriesEnum"`
}
Generics and composition¶
- Generics:
@Success 200 object Page[Pet] "A page of pets"generates aPage_Petschema. - Maps:
@Success 200 object map[string]Pet "Pets by ID"(ormap[]Pet) generates an object withadditionalPropertiesofPet. - Composition:
@Success 200 object JSONResult{data=Order} "Order"replaces thedatafield ofJSONResultwithOrder, the same sugar swag uses.