swag

README

swag

🌍 English ∙ 简体中文

Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).

Contents

• Getting started
• Supported Web Frameworks
• How to use it with Gin
• Implementation Status
• Declarative Comments Format
  • General API Info
  • API Operation
  • Security
• Examples
  • Descriptions over multiple lines
  • User defined structure with an array type
  • Model composition in response
  • Add a headers in response
  • Use multiple path params
  • Example value of struct
  • Description of struct
  • Use swaggertype tag to supported custom type
  • Use swaggerignore tag to exclude a field
  • Add extension info to struct field
  • Rename model to display
  • How to using security annotations
  • Add a description for enum items
• About the Project

Getting started

1. Add comments to your API source code, See Declarative Comments Format.

2. Download swag by using:

$ go get -u github.com/swaggo/swag/cmd/swag

To build from source you need Go (1.13 or newer).

Or download a pre-compiled binary from the release page.

1. Run swag init in the project's root folder which contains the main.go file. This will parse your comments and generate the required files (docs folder and docs/docs.go).

$ swag init

Make sure to import the generated docs/docs.go so that your specific configuration gets init'ed. If your General API annotations do not live in main.go, you can let swag know with -g flag.

swag init -g http/api.go

swag cli

$ swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          Go file path in which 'swagger general API Info' is written (default: "main.go")
   --dir value, -d value                  Directory you want to parse (default: "./")
   --exclude value                        Exclude directories and files when searching, comma separated
   --propertyStrategy value, -p value     Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
   --output value, -o value               Output directory for all the generated files(swagger.json, swagger.yaml and doc.go) (default: "./docs")
   --parseVendor                          Parse go files in 'vendor' folder, disabled by default (default: false)
   --parseDependency                      Parse go files in outside dependency folder, disabled by default (default: false)
   --markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default
   --codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
   --parseInternal                        Parse go files in internal packages, disabled by default (default: false)
   --generatedTime                        Generate timestamp at the top of docs.go, disabled by default (default: false)
   --parseDepth value                     Dependency parse depth (default: 100)
   --help, -h                             show help (default: false)

Supported Web Frameworks

• gin
• echo
• buffalo
• net/http
• flamingo
• fiber
• atreugo

How to use it with Gin

Find the example source code here.

1. After using swag init to generate Swagger 2.0 docs, import the following packages:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

1. Add General API annotations in main.go code:

// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1
// @query.collection.format multi

// @securityDefinitions.basic BasicAuth

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.implicit OAuth2Implicit
// @authorizationurl https://example.com/oauth/authorize
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.password OAuth2Password
// @tokenUrl https://example.com/oauth/token
// @scope.read Grants read access
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

// @securitydefinitions.oauth2.accessCode OAuth2AccessCode
// @tokenUrl https://example.com/oauth/token
// @authorizationurl https://example.com/oauth/authorize
// @scope.admin Grants read and write access to administrative information

// @x-extension-openapi {"example": "value on a json format"}

func main() {
	r := gin.Default()

	c := controller.NewController()

	v1 := r.Group("/api/v1")
	{
		accounts := v1.Group("/accounts")
		{
			accounts.GET(":id", c.ShowAccount)
			accounts.GET("", c.ListAccounts)
			accounts.POST("", c.AddAccount)
			accounts.DELETE(":id", c.DeleteAccount)
			accounts.PATCH(":id", c.UpdateAccount)
			accounts.POST(":id/images", c.UploadAccountImage)
		}
    //...
	}
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.Run(":8080")
}
//...

Additionally some general API info can be set dynamically. The generated code package docs exports SwaggerInfo variable which we can use to set the title, description, version, host and base path programmatically. Example using Gin:

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	"github.com/swaggo/gin-swagger"
	
	"./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @termsOfService http://swagger.io/terms/

func main() {

	// programmatically set swagger info
	docs.SwaggerInfo.Title = "Swagger Example API"
	docs.SwaggerInfo.Description = "This is a sample server Petstore server."
	docs.SwaggerInfo.Version = "1.0"
	docs.SwaggerInfo.Host = "petstore.swagger.io"
	docs.SwaggerInfo.BasePath = "/v2"
	docs.SwaggerInfo.Schemes = []string{"http", "https"}
		
	r := gin.New()

	// use ginSwagger middleware to serve the API docs
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	r.Run()
}

1. Add API Operation annotations in controller code

package controller

import (
	"fmt"
	"net/http"
	"strconv"

	"github.com/gin-gonic/gin"
	"github.com/swaggo/swag/example/celler/httputil"
	"github.com/swaggo/swag/example/celler/model"
)

// ShowAccount godoc
// @Summary Show a account
// @Description get string by ID
// @ID get-string-by-int
// @Accept  json
// @Produce  json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Header 200 {string} Token "qwerty"
// @Failure 400,404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Failure default {object} httputil.DefaultError
// @Router /accounts/{id} [get]
func (c *Controller) ShowAccount(ctx *gin.Context) {
	id := ctx.Param("id")
	aid, err := strconv.Atoi(id)
	if err != nil {
		httputil.NewError(ctx, http.StatusBadRequest, err)
		return
	}
	account, err := model.AccountOne(aid)
	if err != nil {
		httputil.NewError(ctx, http.StatusNotFound, err)
		return
	}
	ctx.JSON(http.StatusOK, account)
}

// ListAccounts godoc
// @Summary List accounts
// @Description get accounts
// @Accept  json
// @Produce  json
// @Param q query string false "name search by q"
// @Success 200 {array} model.Account
// @Header 200 {string} Token "qwerty"
// @Failure 400,404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Failure default {object} httputil.DefaultError
// @Router /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {
	q := ctx.Request.URL.Query().Get("q")
	accounts, err := model.AccountsAll(q)
	if err != nil {
		httputil.NewError(ctx, http.StatusNotFound, err)
		return
	}
	ctx.JSON(http.StatusOK, accounts)
}

//...

$ swag init

1. Run your app, and browse to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as shown below:

Implementation Status

Swagger 2.0 document

• Basic Structure
• API Host and Base Path
• Paths and Operations
• Describing Parameters
• Describing Request Body
• Describing Responses
• MIME Types
• Authentication
  • Basic Authentication
  • API Keys
• Adding Examples
• File Upload
• Enums
• Grouping Operations With Tags
• Swagger Extensions

Declarative Comments Format

General API Info

Example celler/main.go

annotation	description	example
title	Required. The title of the application.	// @title Swagger Example API
version	Required. Provides the version of the application API.	// @version 1.0
description	A short description of the application.	// @description This is a sample server celler server.
tag.name	Name of a tag.	// @tag.name This is the name of the tag
tag.description	Description of the tag	// @tag.description Cool Description
tag.docs.url	Url of the external Documentation of the tag	// @tag.docs.url https://example.com
tag.docs.description	Description of the external Documentation of the tag	// @tag.docs.description Best example documentation
termsOfService	The Terms of Service for the API.	// @termsOfService http://swagger.io/terms/
contact.name	The contact information for the exposed API.	// @contact.name API Support
contact.url	The URL pointing to the contact information. MUST be in the format of a URL.	// @contact.url http://www.swagger.io/support
contact.email	The email address of the contact person/organization. MUST be in the format of an email address.	// @contact.email support@swagger.io
license.name	Required. The license name used for the API.	// @license.name Apache 2.0
license.url	A URL to the license used for the API. MUST be in the format of a URL.	// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host	The host (name or ip) serving the API.	// @host localhost:8080
BasePath	The base path on which the API is served.	// @BasePath /api/v1
query.collection.format	The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default.	// @query.collection.format multi
schemes	The transfer protocol for the operation that separated by spaces.	// @schemes http https
x-name	The extension key, must be start by x- and take only json value	// @x-example-key {"key": "value"}

Using markdown descriptions

When a short string in your documentation is insufficient, or you need images, code examples and things like that you may want to use markdown descriptions. In order to use markdown descriptions use the following annotations.

annotation	description	example
title	Required. The title of the application.	// @title Swagger Example API
version	Required. Provides the version of the application API.	// @version 1.0
description.markdown	A short description of the application. Parsed from the api.md file. This is an alternative to @description	// @description.markdown No value needed, this parses the description from api.md
tag.name	Name of a tag.	// @tag.name This is the name of the tag
tag.description.markdown	Description of the tag this is an alternative to tag.description. The description will be read from a file named like tagname.md	// @tag.description.markdown

API Operation

Example celler/controller

annotation	description
description	A verbose explanation of the operation behavior.
description.markdown	A short description of the application. The description will be read from a file named like endpointname.md
id	A unique string used to identify the operation. Must be unique among all API operations.
tags	A list of tags to each API operation that separated by commas.
summary	A short summary of what the operation does.
accept	A list of MIME types the APIs can consume. Value MUST be as described under Mime Types.
produce	A list of MIME types the APIs can produce. Value MUST be as described under Mime Types.
param	Parameters that separated by spaces. param name,param type,data type,is mandatory?,comment attribute(optional)
security	Security to each API operation.
success	Success response that separated by spaces. return code or default,{param type},data type,comment
failure	Failure response that separated by spaces. return code or default,{param type},data type,comment
response	As same as success and failure
header	Header in response that separated by spaces. return code,{param type},data type,comment
router	Path definition that separated by spaces. path,[httpMethod]
x-name	The extension key, must be start by x- and take only json value.
x-codeSample	Optional Markdown usage. take file as parameter. This will then search for a file named like the summary in the given folder.
deprecated	Mark endpoint as deprecated.

Mime Types

swag accepts all MIME Types which are in the correct format, that is, match */*. Besides that, swag also accepts aliases for some MIME Types as follows:

Alias	MIME Type
json	application/json
xml	text/xml
plain	text/plain
html	text/html
mpfd	multipart/form-data
x-www-form-urlencoded	application/x-www-form-urlencoded
json-api	application/vnd.api+json
json-stream	application/x-json-stream
octet-stream	application/octet-stream
png	image/png
jpeg	image/jpeg
gif	image/gif

Param Type

• query
• path
• header
• body
• formData

Data Type

• string (string)
• integer (int, uint, uint32, uint64)
• number (float32)
• boolean (bool)
• user defined struct

Security

annotation	description	parameters	example
securitydefinitions.basic	Basic auth.		// @securityDefinitions.basic BasicAuth
securitydefinitions.apikey	API key auth.	in, name	// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application	OAuth2 application auth.	tokenUrl, scope	// @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit	OAuth2 implicit auth.	authorizationUrl, scope	// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password	OAuth2 password auth.	tokenUrl, scope	// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode	OAuth2 access code auth.	tokenUrl, authorizationUrl, scope	// @securitydefinitions.oauth2.accessCode OAuth2AccessCode

parameters annotation	example
in	// @in header
name	// @name Authorization
tokenUrl	// @tokenUrl https://example.com/oauth/token
authorizationurl	// @authorizationurl https://example.com/oauth/authorize
scope.hoge	// @scope.write Grants write access

Attribute

// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)
// @Param default query string false "string default" default(A)
// @Param collection query []string false "string collection" collectionFormat(multi)

It also works for the struct fields:

type Foo struct {
    Bar string `minLength:"4" maxLength:"16"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux []string `enums:"foo,bar,baz"`
}

Available

Field Name	Type	Description
validate	string	Determines the validation for the parameter. Possible values are: required.
default	*	Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter.
maximum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
maxLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums	[*]	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
format	string	The extending format for the previously mentioned type. See Data Type Formats for further details.
collectionFormat	string	Determines the format of the array if type array is used. Possible values are: csv - comma separated values foo,bar. ssv - space separated values foo bar. tsv - tab separated values foo\tbar. pipes - pipe separated values foo|bar. multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData". Default value is csv.

Future

Field Name	Type	Description
multipleOf	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern	string	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
uniqueItems	boolean	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.

Examples

Descriptions over multiple lines

You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:

// @description This is the first line
// @description This is the second line
// @description And so forth.

User defined structure with an array type

// @Success 200 {array} model.Account <-- This is a user defined struct.

package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

Model composition in response

// JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"

type JSONResult struct {
    Code    int          `json:"code" `
    Message string       `json:"message"`
    Data    interface{}  `json:"data"`
}

type Order struct { //in `proto` package
    Id  uint            `json:"id"`
    Data  interface{}   `json:"data"`
}

• also support array of objects and primitive types as nested response

@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
@success 200 {object} jsonresult.JSONResult{data=string} "desc"
@success 200 {object} jsonresult.JSONResult{data=[]string} "desc"

• overriding multiple fields. field will be added if not exists

@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"

• overriding deep-level fields

type DeepObject struct { //in `proto` package
	...
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"

Add a headers in response

// @Success 200 {string} string	"ok"
// @failure 400 {string} string	"error"
// @response default {string} string	"other error"
// @Header 200 {string} Location "/entity/1"
// @Header 200,400,default {string} Token "token"
// @Header all {string} Token2 "token2"

Use multiple path params

/// ...
// @Param group_id path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

Example value of struct

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
    PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
}

Description of struct

type Account struct {
	// ID this is userid
	ID   int    `json:"id"`
	Name string `json:"name"` // This is Name
}

Use swaggertype tag to supported custom type

#201

type TimestampTime struct {
    time.Time
}

///implement encoding.JSON.Marshaler interface
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
    bin := make([]byte, 16)
    bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
    return bin, nil
}

func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
    v, err := strconv.ParseInt(string(bin), 10, 64)
    if err != nil {
        return err
    }
    t.Time = time.Unix(v, 0)
    return nil
}
///

type Account struct {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

    // Array types can be overridden using "array,<prim_type>" format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

#379

type CerticateKeyPair struct {
	Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
	Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}

generated swagger doc as follows:

"api.MyBinding": {
  "type":"object",
  "properties":{
    "crt":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    },
    "key":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    }
  }
}

Use swaggerignore tag to exclude a field

type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}

Add extension info to struct field

type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def"` // extensions fields must start with "x-"
}

generate swagger doc as follows:

"Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def"
        }
    }
}

Rename model to display

type Resp struct {
	Code int
}//@name Response

How to using security annotations

General API info.

// @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

Each API operation.

// @Security ApiKeyAuth

Make it AND condition

// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

Add a description for enum items

type Example struct {
	// Sort order:
	// * asc - Ascending, from A to Z.
	// * desc - Descending, from Z to A.
	Order string `enums:"asc,desc"`
}

About the Project

This project was inspired by yvasiyarov/swagger but we simplified the usage and added support a variety of web frameworks. Gopher image source is tenntenn/gopher-stickers. It has licenses creative commons licensing.

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

License

Documentation

Overview

Package swag converts Go annotations to Swagger Documentation 2.0. See https://github.com/swaggo/swag for more information about swag.

Index

• Constants
• Variables
• func BuildCustomSchema(types []string) (*spec.Schema, error)
• func CheckSchemaType(typeName string) error
• func IsGolangPrimitiveType(typeName string) bool
• func IsNumericType(typeName string) bool
• func IsPrimitiveType(typeName string) bool
• func IsSimplePrimitiveType(typeName string) bool
• func PrimitiveSchema(refType string) *spec.Schema
• func Printf(format string, v ...interface{})
• func Println(v ...interface{})
• func ReadDoc() (string, error)
• func RefSchema(refType string) *spec.Schema
• func Register(name string, swagger Swagger)
• func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation)
• func SetCodeExamplesDirectory(directoryPath string) func(*Parser)
• func SetExcludedDirsAndFiles(excludes string) func(*Parser)
• func SetMarkdownFileDirectory(directoryPath string) func(*Parser)
• func TransToValidCollectionFormat(format string) string
• func TransToValidSchemeType(typeName string) string
• func TypeDocName(pkgName string, spec *ast.TypeSpec) string
• type AstFileInfo
• type Operation
  • func NewOperation(parser *Parser, options ...func(*Operation)) *Operation
  • func (operation *Operation) AddResponse(code int, response *spec.Response)
  • func (operation *Operation) DefaultResponse() *spec.Response
  • func (operation *Operation) ParseAcceptComment(commentLine string) error
  • func (operation *Operation) ParseCodeSample(attribute, commentLine, lineRemainder string) error
  • func (operation *Operation) ParseComment(comment string, astFile *ast.File) error
  • func (operation *Operation) ParseDescriptionComment(lineRemainder string)
  • func (operation *Operation) ParseEmptyResponseComment(commentLine string) error
  • func (operation *Operation) ParseEmptyResponseOnly(commentLine string) error
  • func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error
  • func (operation *Operation) ParseParamComment(commentLine string, astFile *ast.File) error
  • func (operation *Operation) ParseProduceComment(commentLine string) error
  • func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error
  • func (operation *Operation) ParseResponseHeaderComment(commentLine string, astFile *ast.File) error
  • func (operation *Operation) ParseRouterComment(commentLine string) error
  • func (operation *Operation) ParseSecurityComment(commentLine string) error
  • func (operation *Operation) ParseTagsComment(commentLine string)
• type PackageDefinitions
• type PackagesDefinitions
  • func NewPackagesDefinitions() *PackagesDefinitions
  • func (pkgs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File)
  • func (pkgs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef
  • func (pkgs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)
  • func (pkgs *PackagesDefinitions) RangeFiles(handle func(filename string, file *ast.File) error) error
• type Parser
  • func New(options ...func(*Parser)) *Parser
  • func (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string
  • func (parser *Parser) GetSwagger() *spec.Swagger
  • func (parser *Parser) ParseAPI(searchDir string, mainAPIFile string, parseDepth int) error
  • func (parser *Parser) ParseAPIMultiSearchDir(searchDirs []string, mainAPIFile string, parseDepth int) error
  • func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)
  • func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error
  • func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error
  • func (parser *Parser) Skip(path string, f os.FileInfo) error
• type Schema
• type Swagger
• type TypeSpecDef
  • func (t *TypeSpecDef) FullName() string
  • func (t *TypeSpecDef) Name() string

Constants

const (
	// CamelCase indicates using CamelCase strategy for struct field.
	CamelCase = "camelcase"

	// PascalCase indicates using PascalCase strategy for struct field.
	PascalCase = "pascalcase"

	// SnakeCase indicates using SnakeCase strategy for struct field.
	SnakeCase = "snakecase"
)

const (
	//ARRAY array
	ARRAY = "array"
	//OBJECT object
	OBJECT = "object"
	//PRIMITIVE primitive
	PRIMITIVE = "primitive"
	//BOOLEAN boolean
	BOOLEAN = "boolean"
	//INTEGER integer
	INTEGER = "integer"
	//NUMBER number
	NUMBER = "number"
	//STRING string
	STRING = "string"
	//FUNC func
	FUNC = "func"
)

const Name = "swagger"

Name is a unique name be used to register swag instance.

const Version = "v1.7.2"

Version of swag

Variables

var (
	//ErrRecursiveParseStruct recursively parsing struct
	ErrRecursiveParseStruct = errors.New("recursively parsing struct")

	//ErrFuncTypeField field type is func
	ErrFuncTypeField = errors.New("field type is func")

	// ErrFailedConvertPrimitiveType Failed to convert for swag to interpretable type
	ErrFailedConvertPrimitiveType = errors.New("swag property: failed convert primitive type")
)

Functions

func BuildCustomSchema

func BuildCustomSchema(types []string) (*spec.Schema, error)

BuildCustomSchema build custom schema specified by tag swaggertype

func CheckSchemaType

func CheckSchemaType(typeName string) error

CheckSchemaType checks if typeName is not a name of primitive type

func IsGolangPrimitiveType

func IsGolangPrimitiveType(typeName string) bool

IsGolangPrimitiveType determine whether the type name is a golang primitive type

func IsNumericType

func IsNumericType(typeName string) bool

IsNumericType determines whether the swagger type name is a numeric type

func IsPrimitiveType

func IsPrimitiveType(typeName string) bool

IsPrimitiveType determine whether the type name is a primitive type

func IsSimplePrimitiveType

func IsSimplePrimitiveType(typeName string) bool

IsSimplePrimitiveType determine whether the type name is a simple primitive type

func PrimitiveSchema

func PrimitiveSchema(refType string) *spec.Schema

PrimitiveSchema build a primitive schema

func Printf

func Printf(format string, v ...interface{})

Printf calls Output to print to the standard logger when release mode.

func Println

func Println(v ...interface{})

Println calls Output to print to the standard logger when release mode.

func ReadDoc

func ReadDoc() (string, error)

ReadDoc reads swagger document.

func RefSchema

func RefSchema(refType string) *spec.Schema

RefSchema build a reference schema

func Register

func Register(name string, swagger Swagger)

Register registers swagger for given name.

func SetCodeExampleFilesDirectory

func SetCodeExampleFilesDirectory(directoryPath string) func(*Operation)

SetCodeExampleFilesDirectory sets the directory to search for codeExamples

func SetCodeExamplesDirectory

func SetCodeExamplesDirectory(directoryPath string) func(*Parser)

SetCodeExamplesDirectory sets the directory to search for code example files

func SetExcludedDirsAndFiles

func SetExcludedDirsAndFiles(excludes string) func(*Parser)

SetExcludedDirsAndFiles sets directories and files to be excluded when searching

func SetMarkdownFileDirectory

func SetMarkdownFileDirectory(directoryPath string) func(*Parser)

SetMarkdownFileDirectory sets the directory to search for markdownfiles

func TransToValidCollectionFormat

func TransToValidCollectionFormat(format string) string

TransToValidCollectionFormat determine valid collection format

func TransToValidSchemeType

func TransToValidSchemeType(typeName string) string

TransToValidSchemeType indicates type will transfer golang basic type to swagger supported type.

func TypeDocName

func TypeDocName(pkgName string, spec *ast.TypeSpec) string

TypeDocName get alias from comment '// @name ', otherwise the original type name to display in doc

Types

type AstFileInfo

type AstFileInfo struct {
	//File ast.File
	File *ast.File

	//Path path of the ast.File
	Path string

	//PackagePath package import path of the ast.File
	PackagePath string
}

AstFileInfo information of a ast.File

type Operation

type Operation struct {
	HTTPMethod string
	Path       string
	spec.Operation
	// contains filtered or unexported fields
}

Operation describes a single API operation on a path. For more information: https://github.com/swaggo/swag#api-operation

func NewOperation

func NewOperation(parser *Parser, options ...func(*Operation)) *Operation

NewOperation creates a new Operation with default properties. map[int]Response

func (*Operation) AddResponse

func (operation *Operation) AddResponse(code int, response *spec.Response)

AddResponse add a response for a code

func (*Operation) DefaultResponse

func (operation *Operation) DefaultResponse() *spec.Response

DefaultResponse return the default response member pointer

func (*Operation) ParseAcceptComment

func (operation *Operation) ParseAcceptComment(commentLine string) error

ParseAcceptComment parses comment for given `accept` comment string.

func (*Operation) ParseCodeSample

func (operation *Operation) ParseCodeSample(attribute, commentLine, lineRemainder string) error

ParseCodeSample godoc

func (*Operation) ParseComment

func (operation *Operation) ParseComment(comment string, astFile *ast.File) error

ParseComment parses comment for given comment string and returns error if error occurs.

func (*Operation) ParseDescriptionComment

func (operation *Operation) ParseDescriptionComment(lineRemainder string)

ParseDescriptionComment godoc

func (*Operation) ParseEmptyResponseComment

func (operation *Operation) ParseEmptyResponseComment(commentLine string) error

ParseEmptyResponseComment parse only comment out status code and description,eg: @Success 200 "it's ok"

func (*Operation) ParseEmptyResponseOnly

func (operation *Operation) ParseEmptyResponseOnly(commentLine string) error

ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200

func (*Operation) ParseMetadata

func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error

ParseMetadata godoc

func (*Operation) ParseParamComment

func (operation *Operation) ParseParamComment(commentLine string, astFile *ast.File) error

ParseParamComment parses params return []string of param properties E.g. @Param queryText formData string true "The email for login"

[param name]    [paramType] [data type]  [is mandatory?]   [Comment]

E.g. @Param some_id path int true "Some ID"

func (*Operation) ParseProduceComment

func (operation *Operation) ParseProduceComment(commentLine string) error

ParseProduceComment parses comment for given `produce` comment string.

func (*Operation) ParseResponseComment

func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error

ParseResponseComment parses comment for given `response` comment string.

func (*Operation) ParseResponseHeaderComment

func (operation *Operation) ParseResponseHeaderComment(commentLine string, astFile *ast.File) error

ParseResponseHeaderComment parses comment for gived `response header` comment string.

func (*Operation) ParseRouterComment

func (operation *Operation) ParseRouterComment(commentLine string) error

ParseRouterComment parses comment for gived `router` comment string.

func (*Operation) ParseSecurityComment

func (operation *Operation) ParseSecurityComment(commentLine string) error

ParseSecurityComment parses comment for gived `security` comment string.

func (*Operation) ParseTagsComment

func (operation *Operation) ParseTagsComment(commentLine string)

ParseTagsComment parses comment for given `tag` comment string.

type PackageDefinitions

type PackageDefinitions struct {
	//package name
	Name string

	//files in this package, map key is file's relative path starting package path
	Files map[string]*ast.File

	//definitions in this package, map key is typeName
	TypeDefinitions map[string]*TypeSpecDef
}

PackageDefinitions files and definition in a package

type PackagesDefinitions

type PackagesDefinitions struct {
	// contains filtered or unexported fields
}

PackagesDefinitions map[package import path]*PackageDefinitions

func NewPackagesDefinitions

func NewPackagesDefinitions() *PackagesDefinitions

NewPackagesDefinitions create object PackagesDefinitions

func (*PackagesDefinitions) CollectAstFile

func (pkgs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File)

CollectAstFile collect ast.file

func (*PackagesDefinitions) FindTypeSpec

func (pkgs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef

FindTypeSpec finds out TypeSpecDef of a type by typeName @typeName the name of the target type, if it starts with a package name, find its own package path from imports on top of @file @file the ast.file in which @typeName is used @pkgPath the package path of @file

func (*PackagesDefinitions) ParseTypes

func (pkgs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)

ParseTypes parse types @Return parsed definitions

func (*PackagesDefinitions) RangeFiles

func (pkgs *PackagesDefinitions) RangeFiles(handle func(filename string, file *ast.File) error) error

RangeFiles for range the collection of ast.File

type Parser

type Parser struct {
	PropNamingStrategy string

	ParseVendor bool

	// ParseDependencies whether swag should be parse outside dependency folder
	ParseDependency bool

	// ParseInternal whether swag should parse internal packages
	ParseInternal bool
	// contains filtered or unexported fields
}

Parser implements a parser for Go source files.

func New

func New(options ...func(*Parser)) *Parser

New creates a new Parser with default properties.

func (*Parser) GetSchemaTypePath

func (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string

GetSchemaTypePath get path of schema type

func (*Parser) GetSwagger

func (parser *Parser) GetSwagger() *spec.Swagger

GetSwagger returns *spec.Swagger which is the root document object for the API specification.

func (*Parser) ParseAPI

func (parser *Parser) ParseAPI(searchDir string, mainAPIFile string, parseDepth int) error

ParseAPI parses general api info for given searchDir and mainAPIFile

func (*Parser) ParseAPIMultiSearchDir

func (parser *Parser) ParseAPIMultiSearchDir(searchDirs []string, mainAPIFile string, parseDepth int) error

ParseAPIMultiSearchDir is like ParseAPI but for multiple search dirs.

func (*Parser) ParseDefinition

func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)

ParseDefinition parses given type spec that corresponds to the type under given name and package, and populates swagger schema definitions registry with a schema for the given type

func (*Parser) ParseGeneralAPIInfo

func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error

ParseGeneralAPIInfo parses general api info for given mainAPIFile path

func (*Parser) ParseRouterAPIInfo

func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error

ParseRouterAPIInfo parses router api info for given astFile

func (*Parser) Skip

func (parser *Parser) Skip(path string, f os.FileInfo) error

Skip returns filepath.SkipDir error if match vendor and hidden folder

type Schema

type Schema struct {
	PkgPath      string //package import path used to rename Name of a definition int case of conflict
	Name         string //Name in definitions
	*spec.Schema        //
}

Schema parsed schema

type Swagger

type Swagger interface {
	ReadDoc() string
}

Swagger is a interface to read swagger document.

type TypeSpecDef

type TypeSpecDef struct {
	//path of package starting from under ${GOPATH}/src or from module path in go.mod
	PkgPath string

	//ast file where TypeSpec is
	File *ast.File

	//the TypeSpec of this type definition
	TypeSpec *ast.TypeSpec
}

TypeSpecDef the whole information of a typeSpec

func (*TypeSpecDef) FullName

func (t *TypeSpecDef) FullName() string

FullName full name of the typeSpec

func (*TypeSpecDef) Name

func (t *TypeSpecDef) Name() string

Name name of the typeSpec