swag

Documentation

Index

• Constants
• Variables
• 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 Printf(format string, v ...interface{})
• func Println(v ...interface{})
• func ReadDoc() (string, error)
• func Register(name string, swagger Swagger)
• 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 Operation
  • func NewOperation() *Operation
  • func (operation *Operation) ParseAcceptComment(commentLine 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 Parser
  • func New(options ...func(*Parser)) *Parser
  • func (parser *Parser) GetSwagger() *spec.Swagger
  • func (parser *Parser) ParseAPI(searchDir string, mainAPIFile string) error
  • func (parser *Parser) ParseDefinition(pkgName, typeName string, typeSpec *ast.TypeSpec) error
  • func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error
  • func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error
  • func (parser *Parser) ParseType(astFile *ast.File)
  • func (parser *Parser) Skip(path string, f os.FileInfo) error
• type Swagger

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 Name = "swagger"

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

const Version = "v1.6.5"

Version of swag

Variables

var ErrFailedConvertPrimitiveType = errors.New("swag property: failed convert primitive type")

ErrFailedConvertPrimitiveType Failed to convert for swag to interpretable type

Functions

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 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 Register

func Register(name string, swagger Swagger)

Register registers swagger for given name.

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 Operation

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

Operation describes a single API operation on a path.

func NewOperation

func NewOperation() *Operation

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

func (*Operation) ParseAcceptComment

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

ParseAcceptComment parses comment for given `accept` comment string.

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 Parser

type Parser struct {

	// TypeDefinitions is a map that stores [package name][type name][*ast.TypeSpec]
	TypeDefinitions map[string]map[string]*ast.TypeSpec

	// ImportAliases is map that stores [import name][import package name][*ast.ImportSpec]
	ImportAliases map[string]map[string]*ast.ImportSpec

	// CustomPrimitiveTypes is a map that stores custom primitive types to actual golang types [type name][string]
	CustomPrimitiveTypes map[string]string

	PropNamingStrategy string

	ParseVendor bool

	// ParseDependencies whether swag should be parse outside dependency folder
	ParseDependency 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) 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) error

ParseAPI parses general api info for given searchDir and mainAPIFile

func (*Parser) ParseDefinition

func (parser *Parser) ParseDefinition(pkgName, typeName string, typeSpec *ast.TypeSpec) 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) ParseType

func (parser *Parser) ParseType(astFile *ast.File)

ParseType parses type 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 Swagger

type Swagger interface {
	ReadDoc() string
}

Swagger is a interface to read swagger document.