swag

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2021 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
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"
)
View Source 
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"
)
View Source 
const Name = "swagger"

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

Variables

View Source 
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, mainAPIFile string, parseDepth int) error

ParseAPI parses general api info for given searchDir and mainAPIFile

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.