Go Swagger3 Docs

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

package main

// @Title User API
// @Version 1.0
// @Description User and restaurants API
// @ContactName API Support
// @ContactEmail support@example.com
// @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() {}

// 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"`
}

// @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() {}

// @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() {}

// @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() {}

// @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() {}

// @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() {}

// @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() {}

// @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"`
}

// 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

// 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"`
}