README
¶
swag

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
- 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
- About the Project
Getting started
-
Add comments to your API source code, See Declarative Comments Format.
-
Download swag by using:
$ go get -u github.com/swaggo/swag/cmd/swag
To build from source you need Go (1.9 or newer).
Or download a pre-compiled binary from the release page.
- Run
swag init
in the project's root folder which contains themain.go
file. This will parse your comments and generate the required files (docs
folder anddocs/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
How to use it with Gin
Find the example source code here.
- 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
- 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()
}
- 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
- 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
- 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 . |
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
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"`
}
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]
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 (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 (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 (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string
- func (parser *Parser) GetSwagger() *spec.Swagger
- func (parser *Parser) ParseAPI(searchDir, 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
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.0"
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 ¶
BuildCustomSchema build custom schema specified by tag swaggertype
func CheckSchemaType ¶
CheckSchemaType checks if typeName is not a name of primitive type
func IsGolangPrimitiveType ¶
IsGolangPrimitiveType determine whether the type name is a golang primitive type
func IsNumericType ¶
IsNumericType determines whether the swagger type name is a numeric type
func IsPrimitiveType ¶
IsPrimitiveType determine whether the type name is a primitive type
func IsSimplePrimitiveType ¶
IsSimplePrimitiveType determine whether the type name is a simple primitive type
func PrimitiveSchema ¶
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 SetCodeExampleFilesDirectory ¶
SetCodeExampleFilesDirectory sets the directory to search for codeExamples
func SetCodeExamplesDirectory ¶
SetCodeExamplesDirectory sets the directory to search for code example files
func SetExcludedDirsAndFiles ¶
SetExcludedDirsAndFiles sets directories and files to be excluded when searching
func SetMarkdownFileDirectory ¶
SetMarkdownFileDirectory sets the directory to search for markdownfiles
func TransToValidCollectionFormat ¶
TransToValidCollectionFormat determine valid collection format
func TransToValidSchemeType ¶
TransToValidSchemeType indicates type will transfer golang basic type to swagger supported type.
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 ¶
NewOperation creates a new Operation with default properties. map[int]Response
func (*Operation) AddResponse ¶
AddResponse add a response for a code
func (*Operation) DefaultResponse ¶
DefaultResponse return the default response member pointer
func (*Operation) ParseAcceptComment ¶
ParseAcceptComment parses comment for given `accept` comment string.
func (*Operation) ParseCodeSample ¶
ParseCodeSample godoc
func (*Operation) ParseComment ¶
ParseComment parses comment for given comment string and returns error if error occurs.
func (*Operation) ParseDescriptionComment ¶
ParseDescriptionComment godoc
func (*Operation) ParseEmptyResponseComment ¶
ParseEmptyResponseComment parse only comment out status code and description,eg: @Success 200 "it's ok"
func (*Operation) ParseEmptyResponseOnly ¶
ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200
func (*Operation) ParseMetadata ¶
ParseMetadata godoc
func (*Operation) ParseParamComment ¶
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 ¶
ParseProduceComment parses comment for given `produce` comment string.
func (*Operation) ParseResponseComment ¶
ParseResponseComment parses comment for given `response` comment string.
func (*Operation) ParseResponseHeaderComment ¶
ParseResponseHeaderComment parses comment for gived `response header` comment string.
func (*Operation) ParseRouterComment ¶
ParseRouterComment parses comment for gived `router` comment string.
func (*Operation) ParseSecurityComment ¶
ParseSecurityComment parses comment for gived `security` comment string.
func (*Operation) ParseTagsComment ¶
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 (*Parser) GetSchemaTypePath ¶
GetSchemaTypePath get path of schema type
func (*Parser) GetSwagger ¶
GetSwagger returns *spec.Swagger which is the root document object for the API specification.
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 ¶
ParseGeneralAPIInfo parses general api info for given mainAPIFile path
func (*Parser) ParseRouterAPIInfo ¶
ParseRouterAPIInfo parses router api info for given astFile
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
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
example
|
|
celler
Module
|
|
go-module-support
Module
|
|
markdown
Module
|
|
object-map-example
Module
|
|