Documentation
¶
Overview ¶
Package swag converts Go annotations to Swagger Documentation 2.0. See https://github.com/ezequiel/swag for more information about swag.
Index ¶
- Constants
- Variables
- func BuildCustomSchema(types []string) (*spec.Schema, error)
- func CheckSchemaType(typeName string) error
- func EvaluateBinary(x, y interface{}, operator token.Token, xtype, ytype ast.Expr) (interface{}, ast.Expr)
- func EvaluateDataConversion(x interface{}, typeName string) interface{}
- func EvaluateEscapedChar(text string) rune
- func EvaluateEscapedString(text string) string
- func EvaluateUnary(x interface{}, operator token.Token, xtype ast.Expr) (interface{}, ast.Expr)
- func FieldsByAnySpace(s string, n int) []string
- func FieldsFunc(s string, f func(rune2 rune) bool, n int) []string
- func IsComplexSchema(schema *spec.Schema) bool
- func IsGolangPrimitiveType(typeName string) bool
- func IsInterfaceLike(typeName string) bool
- func IsNumericType(typeName string) bool
- func IsPrimitiveType(typeName string) bool
- func IsRefSchema(schema *spec.Schema) bool
- func IsSimplePrimitiveType(typeName string) bool
- func MergeSchema(dst *spec.Schema, src *spec.Schema) *spec.Schema
- func ParseUsingGoList(enabled bool) func(parser *Parser)
- func PrimitiveSchema(refType string) *spec.Schema
- func ReadDoc(optionalName ...string) (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 SetCollectionFormat(collectionFormat string) func(*Parser)
- func SetDebugger(logger Debugger) func(parser *Parser)
- func SetExcludedDirsAndFiles(excludes string) func(*Parser)
- func SetFieldParserFactory(factory FieldParserFactory) func(parser *Parser)
- func SetMarkdownFileDirectory(directoryPath string) func(*Parser)
- func SetOverrides(overrides map[string]string) func(parser *Parser)
- func SetPackagePrefix(packagePrefix string) func(*Parser)
- func SetParseDependency(parseDependency int) func(*Parser)
- func SetParseExtension(parseExtension string) func(*Parser)
- func SetStrict(strict bool) func(*Parser)
- func SetTags(include string) func(*Parser)
- func TransToValidCollectionFormat(format string) string
- func TransToValidSchemeType(typeName string) string
- type AstFileInfo
- type ConstVariable
- type ConstVariableGlobalEvaluator
- type Debugger
- type EnumValue
- type FieldParser
- type FieldParserFactory
- type Formatter
- 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, _, 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, _ *ast.File) error
- func (operation *Operation) ParseRouterComment(commentLine string, deprecated bool) error
- func (operation *Operation) ParseSecurityComment(commentLine string) error
- func (operation *Operation) ParseStateComment(lineRemainder string)
- func (operation *Operation) ParseTagsComment(commentLine string)
- type PackageDefinitions
- type PackagesDefinitions
- func (pkgDefs *PackagesDefinitions) EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr)
- func (pkgDefs *PackagesDefinitions) EvaluateConstValueByName(file *ast.File, pkgName, constVariableName string, ...) (interface{}, ast.Expr)
- func (pkgDefs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef
- func (pkgDefs *PackagesDefinitions) ParseFile(packageDir, path string, src interface{}, flag ParseFlag) error
- func (pkgDefs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)
- func (pkgDefs *PackagesDefinitions) RangeFiles(handle func(info *AstFileInfo) error) error
- type ParseFlag
- type 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) ParseAcceptComment(commentLine string) error
- func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)
- func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error
- func (parser *Parser) ParseProduceComment(commentLine string) error
- func (parser *Parser) ParseRouterAPIInfo(fileInfo *AstFileInfo) error
- func (parser *Parser) Skip(path string, f os.FileInfo) error
- type RouteProperties
- type Schema
- type Spec
- 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 ( // ParseNone parse nothing ParseNone ParseFlag = 0x00 // ParseModels parse models ParseModels = 0x01 // ParseOperations parse operations ParseOperations = 0x02 // ParseAll parse operations and models ParseAll = ParseOperations | ParseModels )
const ( // ARRAY represent a array value. ARRAY = "array" // OBJECT represent a object value. OBJECT = "object" // PRIMITIVE represent a primitive value. PRIMITIVE = "primitive" // BOOLEAN represent a boolean value. BOOLEAN = "boolean" // INTEGER represent a integer value. INTEGER = "integer" // NUMBER represent a number value. NUMBER = "number" // STRING represent a string value. STRING = "string" // FUNC represent a function value. FUNC = "func" // ERROR represent a error value. ERROR = "error" // INTERFACE represent a interface value. INTERFACE = "interface{}" // ANY represent a any value. ANY = "any" // NIL represent a empty value. NIL = "nil" // IgnoreNameOverridePrefix Prepend to model to avoid renaming based on comment. IgnoreNameOverridePrefix = '$' )
const Name = "swagger"
Name is a unique name be used to register swag instance.
const Version = "v1.16.3"
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") // ErrSkippedField .swaggo specifies field should be skipped. ErrSkippedField = errors.New("field is skipped by global overrides") )
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 EvaluateBinary ¶
func EvaluateBinary(x, y interface{}, operator token.Token, xtype, ytype ast.Expr) (interface{}, ast.Expr)
EvaluateBinary evaluate the type and value of a binary expression
func EvaluateDataConversion ¶
func EvaluateDataConversion(x interface{}, typeName string) interface{}
EvaluateDataConversion evaluate the type a explicit type conversion
func EvaluateEscapedChar ¶
EvaluateEscapedChar parse escaped character
func EvaluateEscapedString ¶
EvaluateEscapedString parse escaped characters in string
func EvaluateUnary ¶
EvaluateUnary evaluate the type and value of a unary expression
func FieldsByAnySpace ¶
FieldsByAnySpace split a string s by any space character into max n parts
func FieldsFunc ¶
FieldsFunc split a string s by a func splitter into max n parts
func IsComplexSchema ¶
IsComplexSchema whether a schema is complex and should be a ref schema
func IsGolangPrimitiveType ¶
IsGolangPrimitiveType determine whether the type name is a golang primitive type.
func IsInterfaceLike ¶
IsInterfaceLike determines whether the swagger type name is an go named interface type like error 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 IsRefSchema ¶
IsRefSchema whether a schema is a reference schema.
func IsSimplePrimitiveType ¶
IsSimplePrimitiveType determine whether the type name is a simple primitive type.
func MergeSchema ¶
MergeSchema merge schemas
func ParseUsingGoList ¶
ParseUsingGoList sets whether swag use go list to parse dependency
func PrimitiveSchema ¶
PrimitiveSchema build a primitive schema.
func ReadDoc ¶
ReadDoc reads swagger document. An optional name parameter can be passed to read a specific document. The default name is "swagger".
func SetCodeExampleFilesDirectory ¶
SetCodeExampleFilesDirectory sets the directory to search for codeExamples.
func SetCodeExamplesDirectory ¶
SetCodeExamplesDirectory sets the directory to search for code example files.
func SetCollectionFormat ¶
SetCollectionFormat set default collection format
func SetDebugger ¶
SetDebugger allows the use of user-defined implementations.
func SetExcludedDirsAndFiles ¶
SetExcludedDirsAndFiles sets directories and files to be excluded when searching.
func SetFieldParserFactory ¶
func SetFieldParserFactory(factory FieldParserFactory) func(parser *Parser)
SetFieldParserFactory allows the use of user-defined implementations.
func SetMarkdownFileDirectory ¶
SetMarkdownFileDirectory sets the directory to search for markdown files.
func SetOverrides ¶
SetOverrides allows the use of user-defined global type overrides.
func SetPackagePrefix ¶
SetPackagePrefix sets a list of package path prefixes from a comma-separated string, packages that do not match any one of them will be excluded when searching.
func SetParseDependency ¶
SetParseDependency sets whether to parse the dependent packages.
func SetParseExtension ¶
SetParseExtension parses only those operations which match given extension
func SetStrict ¶
SetStrict sets whether swag should error or warn when it detects cases which are most likely user errors.
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 { //FileSet the FileSet object which is used to parse this go source file FileSet *token.FileSet // File ast.File File *ast.File // Path the path of the ast.File Path string // PackagePath package import path of the ast.File PackagePath string // ParseFlag determine what to parse ParseFlag ParseFlag }
AstFileInfo information of an ast.File.
type ConstVariable ¶
type ConstVariable struct { Name *ast.Ident Type ast.Expr Value interface{} Comment *ast.CommentGroup File *ast.File Pkg *PackageDefinitions }
ConstVariable a model to record a const variable
type ConstVariableGlobalEvaluator ¶
type ConstVariableGlobalEvaluator interface { EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr) EvaluateConstValueByName(file *ast.File, pkgPath, constVariableName string, recursiveStack map[string]struct{}) (interface{}, ast.Expr) FindTypeSpec(typeName string, file *ast.File) *TypeSpecDef }
ConstVariableGlobalEvaluator an interface used to evaluate enums across packages
type Debugger ¶
type Debugger interface {
Printf(format string, v ...interface{})
}
Debugger is the interface that wraps the basic Printf method.
type EnumValue ¶
type EnumValue struct { Value interface{} Comment string // contains filtered or unexported fields }
EnumValue a model to record an enum consts variable
type FieldParser ¶
type FieldParser interface { ShouldSkip() bool FieldName() (string, error) FormName() string HeaderName() string PathName() string CustomSchema() (*spec.Schema, error) ComplementSchema(schema *spec.Schema) error IsRequired() (bool, error) }
FieldParser parse struct field.
type FieldParserFactory ¶
type FieldParserFactory func(ps *Parser, field *ast.Field) FieldParser
FieldParserFactory create FieldParser.
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter implements a formatter for Go source files.
type Operation ¶
type Operation struct { spec.Operation RouterProperties []RouteProperties State string // contains filtered or unexported fields }
Operation describes a single API operation on a path. For more information: https://github.com/ezequiel/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 parse code sample.
func (*Operation) ParseComment ¶
ParseComment parses comment for given comment string and returns error if error occurs.
func (*Operation) ParseDescriptionComment ¶
ParseDescriptionComment parse description comment.
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 parse metadata.
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 given `response header` comment string.
func (*Operation) ParseRouterComment ¶
ParseRouterComment parses comment for given `router` comment string.
func (*Operation) ParseSecurityComment ¶
ParseSecurityComment parses comment for given `security` comment string.
func (*Operation) ParseStateComment ¶
ParseStateComment parse state comment.
func (*Operation) ParseTagsComment ¶
ParseTagsComment parses comment for given `tag` comment string.
type PackageDefinitions ¶
type PackageDefinitions struct { // 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 // const variables in this package, map key is the name ConstTable map[string]*ConstVariable // const variables in order in this package OrderedConst []*ConstVariable // package name Name string // package path Path string }
PackageDefinitions files and definition in a package.
func NewPackageDefinitions ¶
func NewPackageDefinitions(name, pkgPath string) *PackageDefinitions
NewPackageDefinitions new a PackageDefinitions object
func (*PackageDefinitions) AddConst ¶
func (pkg *PackageDefinitions) AddConst(astFile *ast.File, valueSpec *ast.ValueSpec) *PackageDefinitions
AddConst add a const variable.
func (*PackageDefinitions) AddFile ¶
func (pkg *PackageDefinitions) AddFile(pkgPath string, file *ast.File) *PackageDefinitions
AddFile add a file
func (*PackageDefinitions) AddTypeSpec ¶
func (pkg *PackageDefinitions) AddTypeSpec(name string, typeSpec *TypeSpecDef) *PackageDefinitions
AddTypeSpec add a type spec.
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) EvaluateConstValue ¶
func (pkgDefs *PackagesDefinitions) EvaluateConstValue(pkg *PackageDefinitions, cv *ConstVariable, recursiveStack map[string]struct{}) (interface{}, ast.Expr)
EvaluateConstValue evaluate a const variable.
func (*PackagesDefinitions) EvaluateConstValueByName ¶
func (pkgDefs *PackagesDefinitions) EvaluateConstValueByName(file *ast.File, pkgName, constVariableName string, recursiveStack map[string]struct{}) (interface{}, ast.Expr)
EvaluateConstValueByName evaluate a const variable by name.
func (*PackagesDefinitions) FindTypeSpec ¶
func (pkgDefs *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) ParseFile ¶
func (pkgDefs *PackagesDefinitions) ParseFile(packageDir, path string, src interface{}, flag ParseFlag) error
ParseFile parse a source file.
func (*PackagesDefinitions) ParseTypes ¶
func (pkgDefs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)
ParseTypes parse types @Return parsed definitions.
func (*PackagesDefinitions) RangeFiles ¶
func (pkgDefs *PackagesDefinitions) RangeFiles(handle func(info *AstFileInfo) error) error
RangeFiles for range the collection of ast.File in alphabetic order.
type Parser ¶
type Parser struct { // PropNamingStrategy naming strategy PropNamingStrategy string // ParseVendor parse vendor folder ParseVendor bool // ParseDependencies whether swag should be parse outside dependency folder: 0 none, 1 models, 2 operations, 3 all ParseDependency ParseFlag // ParseInternal whether swag should parse internal packages ParseInternal bool // Strict whether swag should error or warn when it detects cases which are most likely user errors Strict bool // RequiredByDefault set validation required for all fields by default RequiredByDefault bool // Overrides allows global replacements of types. A blank replacement will be skipped. Overrides map[string]string // HostState is the state of the host HostState string // ParseFuncBody whether swag should parse api info inside of funcs ParseFuncBody 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) ParseAPIMultiSearchDir ¶
func (parser *Parser) ParseAPIMultiSearchDir(searchDirs []string, mainAPIFile string, parseDepth int) error
ParseAPIMultiSearchDir is like ParseAPI but for multiple search dirs.
func (*Parser) ParseAcceptComment ¶
ParseAcceptComment parses comment for given `accept` comment string.
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) ParseProduceComment ¶
ParseProduceComment parses comment for given `produce` comment string.
func (*Parser) ParseRouterAPIInfo ¶
func (parser *Parser) ParseRouterAPIInfo(fileInfo *AstFileInfo) error
ParseRouterAPIInfo parses router api info for given astFile.
type RouteProperties ¶
RouteProperties describes HTTP properties of a single router comment.
type Schema ¶
type Schema struct { *spec.Schema // PkgPath string // package import path used to rename Name of a definition int case of conflict Name string // Name in definitions }
Schema parsed schema.
type Spec ¶
type Spec struct { Version string Host string BasePath string Schemes []string Title string Description string InfoInstanceName string SwaggerTemplate string LeftDelim string RightDelim string }
Spec holds exported Swagger Info so clients can modify it.
func (*Spec) InstanceName ¶
InstanceName returns Spec instance name.
type Swagger ¶
type Swagger interface {
ReadDoc() string
}
Swagger is an interface to read swagger document.
func GetSwagger ¶
GetSwagger returns the swagger instance for given name. If not found, returns nil.
type TypeSpecDef ¶
type TypeSpecDef struct { // ast file where TypeSpec is File *ast.File // the TypeSpec of this type definition TypeSpec *ast.TypeSpec Enums []EnumValue // path of package starting from under ${GOPATH}/src or from module path in go.mod PkgPath string ParentSpec ast.Decl NotUnique bool }
TypeSpecDef the whole information of a typeSpec.
func (*TypeSpecDef) FullPath ¶
func (t *TypeSpecDef) FullPath() string
FullPath return the full path of the typeSpec.
func (*TypeSpecDef) TypeName ¶
func (t *TypeSpecDef) TypeName() string
TypeName the type name of the typeSpec.
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
example
|
|
basic/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
|
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag |
override/docs
Package docs GENERATED BY SWAG; DO NOT EDIT This file was generated by swaggo/swag
|
Package docs GENERATED BY SWAG; DO NOT EDIT This file was generated by swaggo/swag |
celler
Module
|
|
go-module-support
Module
|
|
markdown
Module
|
|
object-map-example
Module
|
|