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 IsInterfaceLike(typeName string) bool
- func IsNumericType(typeName string) bool
- func IsPrimitiveType(typeName string) bool
- func IsSimplePrimitiveType(typeName string) bool
- 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 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 SetStrict(strict bool) func(*Parser)
- func TransToValidCollectionFormat(format string) string
- func TransToValidSchemeType(typeName string) string
- func TypeDocName(pkgName string, spec *ast.TypeSpec) string
- type AstFileInfo
- type Debugger
- 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) error
- func (operation *Operation) ParseSecurityComment(commentLine string) error
- func (operation *Operation) ParseTagsComment(commentLine string)
- type PackageDefinitions
- type PackagesDefinitions
- func (pkgDefs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File) error
- func (pkgDefs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File, parseDependency bool) *TypeSpecDef
- func (pkgDefs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)
- 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(fileName string, astFile *ast.File) 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 ( // 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" )
const Name = "swagger"
Name is a unique name be used to register swag instance.
const Version = "v1.8.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 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 IsSimplePrimitiveType ¶
IsSimplePrimitiveType determine whether the type name is a simple primitive type.
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 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 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 { // 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 }
AstFileInfo information of an ast.File.
type Debugger ¶
type Debugger interface {
Printf(format string, v ...interface{})
}
Debugger is the interface that wraps the basic Printf method.
type FieldParser ¶
type FieldParser interface { ShouldSkip() bool FieldName() (string, error) 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 // 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 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) 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 // package name Name string }
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 (pkgDefs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File) error
CollectAstFile collect ast.file.
func (*PackagesDefinitions) FindTypeSpec ¶
func (pkgDefs *PackagesDefinitions) FindTypeSpec(typeName string, file *ast.File, parseDependency bool) *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 (pkgDefs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)
ParseTypes parse types @Return parsed definitions.
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 ParseDependency bool // 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 // 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 ¶
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 }
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.
type TypeSpecDef ¶
type TypeSpecDef struct { // ast file where TypeSpec is File *ast.File // the TypeSpec of this type definition TypeSpec *ast.TypeSpec // path of package starting from under ${GOPATH}/src or from module path in go.mod PkgPath string }
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
|
|
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 |