swag: github.com/swaggo/swag Index | Files | Directories

package swag

import "github.com/swaggo/swag"

Package swag converts Go annotations to Swagger Documentation 2.0. See https://github.com/swaggo/swag for more information about swag.

Index

Package Files

debug.go doc.go operation.go packages.go parser.go schema.go swagger.go types.go version.go

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.6.7"

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")
)

func BuildCustomSchema Uses

func BuildCustomSchema(types []string) (*spec.Schema, error)

BuildCustomSchema build custom schema specified by tag swaggertype

func CheckSchemaType Uses

func CheckSchemaType(typeName string) error

CheckSchemaType checks if typeName is not a name of primitive type

func IsGolangPrimitiveType Uses

func IsGolangPrimitiveType(typeName string) bool

IsGolangPrimitiveType determine whether the type name is a golang primitive type

func IsNumericType Uses

func IsNumericType(typeName string) bool

IsNumericType determines whether the swagger type name is a numeric type

func IsPrimitiveType Uses

func IsPrimitiveType(typeName string) bool

IsPrimitiveType determine whether the type name is a primitive type

func IsSimplePrimitiveType Uses

func IsSimplePrimitiveType(typeName string) bool

IsSimplePrimitiveType determine whether the type name is a simple primitive type

func PrimitiveSchema Uses

func PrimitiveSchema(refType string) *spec.Schema

PrimitiveSchema build a primitive schema

func Printf Uses

func Printf(format string, v ...interface{})

Printf calls Output to print to the standard logger when release mode.

func Println Uses

func Println(v ...interface{})

Println calls Output to print to the standard logger when release mode.

func ReadDoc Uses

func ReadDoc() (string, error)

ReadDoc reads swagger document.

func RefSchema Uses

func RefSchema(refType string) *spec.Schema

RefSchema build a reference schema

func Register Uses

func Register(name string, swagger Swagger)

Register registers swagger for given name.

func SetExcludedDirsAndFiles Uses

func SetExcludedDirsAndFiles(excludes string) func(*Parser)

SetExcludedDirsAndFiles sets directories and files to be excluded when searching

func SetMarkdownFileDirectory Uses

func SetMarkdownFileDirectory(directoryPath string) func(*Parser)

SetMarkdownFileDirectory sets the directory to search for markdownfiles

func TransToValidCollectionFormat Uses

func TransToValidCollectionFormat(format string) string

TransToValidCollectionFormat determine valid collection format

func TransToValidSchemeType Uses

func TransToValidSchemeType(typeName string) string

TransToValidSchemeType indicates type will transfer golang basic type to swagger supported type.

func TypeDocName Uses

func TypeDocName(pkgName string, spec *ast.TypeSpec) string

TypeDocName get alias from comment '// @name ', otherwise the original type name to display in doc

type AstFileInfo Uses

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 Uses

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 Uses

func NewOperation(parser *Parser) *Operation

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

func (*Operation) ParseAcceptComment Uses

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

ParseAcceptComment parses comment for given `accept` comment string.

func (*Operation) ParseComment Uses

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 Uses

func (operation *Operation) ParseDescriptionComment(lineRemainder string)

ParseDescriptionComment godoc

func (*Operation) ParseEmptyResponseComment Uses

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 Uses

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

ParseEmptyResponseOnly parse only comment out status code ,eg: @Success 200

func (*Operation) ParseMetadata Uses

func (operation *Operation) ParseMetadata(attribute, lowerAttribute, lineRemainder string) error

ParseMetadata godoc

func (*Operation) ParseParamComment Uses

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 Uses

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

ParseProduceComment parses comment for given `produce` comment string.

func (*Operation) ParseResponseComment Uses

func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error

ParseResponseComment parses comment for given `response` comment string.

func (*Operation) ParseResponseHeaderComment Uses

func (operation *Operation) ParseResponseHeaderComment(commentLine string, astFile *ast.File) error

ParseResponseHeaderComment parses comment for gived `response header` comment string.

func (*Operation) ParseRouterComment Uses

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

ParseRouterComment parses comment for gived `router` comment string.

func (*Operation) ParseSecurityComment Uses

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

ParseSecurityComment parses comment for gived `security` comment string.

func (*Operation) ParseTagsComment Uses

func (operation *Operation) ParseTagsComment(commentLine string)

ParseTagsComment parses comment for given `tag` comment string.

type PackageDefinitions Uses

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 Uses

type PackagesDefinitions struct {
    // contains filtered or unexported fields
}

PackagesDefinitions map[package import path]*PackageDefinitions

func NewPackagesDefinitions Uses

func NewPackagesDefinitions() *PackagesDefinitions

NewPackagesDefinitions create object PackagesDefinitions

func (*PackagesDefinitions) CollectAstFile Uses

func (pkgs *PackagesDefinitions) CollectAstFile(packageDir, path string, astFile *ast.File)

CollectAstFile collect ast.file

func (*PackagesDefinitions) FindTypeSpec Uses

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 Uses

func (pkgs *PackagesDefinitions) ParseTypes() (map[*TypeSpecDef]*Schema, error)

ParseTypes parse types @Return parsed definitions

func (*PackagesDefinitions) RangeFiles Uses

func (pkgs *PackagesDefinitions) RangeFiles(handle func(filename string, file *ast.File) error) error

RangeFiles for range the collection of ast.File

type Parser Uses

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 Uses

func New(options ...func(*Parser)) *Parser

New creates a new Parser with default properties.

func (*Parser) GetSchemaTypePath Uses

func (parser *Parser) GetSchemaTypePath(schema *spec.Schema, depth int) []string

GetSchemaTypePath get path of schema type

func (*Parser) GetSwagger Uses

func (parser *Parser) GetSwagger() *spec.Swagger

GetSwagger returns *spec.Swagger which is the root document object for the API specification.

func (*Parser) ParseAPI Uses

func (parser *Parser) ParseAPI(searchDir, mainAPIFile string, parseDepth int) error

ParseAPI parses general api info for given searchDir and mainAPIFile

func (*Parser) ParseDefinition Uses

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 Uses

func (parser *Parser) ParseGeneralAPIInfo(mainAPIFile string) error

ParseGeneralAPIInfo parses general api info for given mainAPIFile path

func (*Parser) ParseRouterAPIInfo Uses

func (parser *Parser) ParseRouterAPIInfo(fileName string, astFile *ast.File) error

ParseRouterAPIInfo parses router api info for given astFile

func (*Parser) Skip Uses

func (parser *Parser) Skip(path string, f os.FileInfo) error

Skip returns filepath.SkipDir error if match vendor and hidden folder

type Schema Uses

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 Uses

type Swagger interface {
    ReadDoc() string
}

Swagger is a interface to read swagger document.

type TypeSpecDef Uses

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 Uses

func (t *TypeSpecDef) FullName() string

FullName full name of the typeSpec

func (*TypeSpecDef) Name Uses

func (t *TypeSpecDef) Name() string

Name name of the typeSpec

Directories

PathSynopsis
cmd/swag
example/basic
example/basic/api
example/basic/docs
example/basic/web
example/celler
example/celler/controller
example/celler/docs
example/celler/httputil
example/celler/model
example/go-module-support
example/go-module-support/web
example/markdown
example/markdown/api
example/markdown/docs
gen

Package swag imports 24 packages (graph) and is imported by 100 packages. Updated 2020-09-21. Refresh now. Tools for package owners.