scan

Documentation

Overview

Package scan provides a scanner for go files that produces a swagger spec document.

You give it a main file and it will parse all the files that are required by that main package to produce a swagger specification.

To use you can add a go:generate comment to your main file for example:

//go:generate swagger generate spec

The following annotations exist:

swagger:meta

The swagger:meta annotation flags a file as source for metadata about the API. This is typically a doc.go file with your package documentation.

You can specify a Consumes and Produces key which has a new content type on each line Schemes is a tag that is required and allows for a comma separated string composed of: http, https, ws or wss

Host and BasePath can be specified but those values will be defaults, they should get substituted when serving the swagger spec.

Default parameters and responses are not supported at this stage, for those you can edit the template json.

swagger:strfmt [name]

A swagger:strfmt annotation names a type as a string formatter. The name is mandatory and that is what will be used as format name for this particular string format. String formats should only be used for very well known formats.

swagger:model [?model name]

A swagger:model annotation optionally gets a model name as extra data on the line. when this appears anywhere in a comment for a struct, then that struct becomes a schema in the definitions object of swagger.

The struct gets analyzed and all the collected models are added to the tree. The refs are tracked separately so that they can be renamed later on.

When this annotation is found to be on an interface instead of a struct, the properties are provided through exported nullary methods.

A property of an interface model can have a Discriminator: true annotation to mark that field as the field that will contain the discriminator value.

swagger:route [method] [path pattern] [operation id] [?tag1 tag2 tag3]

A swagger:route annotation links a path to a method. This operation gets a unique id, which is used in various places as method name. One such usage is in method names for client generation for example.

Because there are many routers available, this tool does not try to parse the paths you provided to your routing library of choice. So you have to specify your path pattern yourself in valid swagger syntax.

swagger:params [operationid1 operationid2]

Links a struct to one or more operations. The params in the resulting swagger spec can be composed of several structs. There are no guarantees given on how property name overlaps are resolved when several structs apply to the same operation. This tag works very similarly to the swagger:model tag except that it produces valid parameter objects instead of schema objects.

swagger:response [?response name]

Reads a struct decorated with swagger:response and uses that information to fill up the headers and the schema for a response. A swagger:route can specify a response name for a status code and then the matching response will be used for that operation in the swagger definition.

Index

• Constants
• Variables
• func Application(opts Opts) (*spec.Swagger, error)
• type Opts

Constants

const (
	// ParamDescriptionKey indicates the tag used to define a parameter description in swagger:route
	ParamDescriptionKey = "description"
	// ParamNameKey indicates the tag used to define a parameter name in swagger:route
	ParamNameKey = "name"
	// ParamInKey indicates the tag used to define a parameter location in swagger:route
	ParamInKey = "in"
	// ParamRequiredKey indicates the tag used to declare whether a parameter is required in swagger:route
	ParamRequiredKey = "required"
	// ParamTypeKey indicates the tag used to define the parameter type in swagger:route
	ParamTypeKey = "type"
	// ParamAllowEmptyKey indicates the tag used to indicate whether a parameter allows empty values in swagger:route
	ParamAllowEmptyKey = "allowempty"

	// SchemaMinKey indicates the tag used to indicate the minimum value allowed for this type in swagger:route
	SchemaMinKey = "min"
	// SchemaMaxKey indicates the tag used to indicate the maximum value allowed for this type in swagger:route
	SchemaMaxKey = "max"
	// SchemaEnumKey indicates the tag used to specify the allowed values for this type in swagger:route
	SchemaEnumKey = "enum"
	// SchemaFormatKey indicates the expected format for this field in swagger:route
	SchemaFormatKey = "format"
	// SchemaDefaultKey indicates the default value for this field in swagger:route
	SchemaDefaultKey = "default"
	// SchemaMinLenKey indicates the minimum length this field in swagger:route
	SchemaMinLenKey = "minlength"
	// SchemaMaxLenKey indicates the minimum length this field in swagger:route
	SchemaMaxLenKey = "maxlength"

	// TypeArray is the identifier for an array type in swagger:route
	TypeArray = "array"
	// TypeNumber is the identifier for a number type in swagger:route
	TypeNumber = "number"
	// TypeInteger is the identifier for an integer type in swagger:route
	TypeInteger = "integer"
	// TypeBoolean is the identifier for a boolean type in swagger:route
	TypeBoolean = "boolean"
	// TypeBool is the identifier for a boolean type in swagger:route
	TypeBool = "bool"
	// TypeObject is the identifier for an object type in swagger:route
	TypeObject = "object"
	// TypeString is the identifier for a string type in swagger:route
	TypeString = "string"
)

const BodyTag = "body"

BodyTag used when specifying a response to point to a model/schema

const DescriptionTag = "description"

DescriptionTag used when specifying a response that gives a description of the response

const ResponseTag = "response"

ResponseTag used when specifying a response to point to a defined swagger:response

Variables

var Debug = safeConvert(os.Getenv("DEBUG"))

Debug is true when process is run with DEBUG=1 env var

Functions

func Application

func Application(opts Opts) (*spec.Swagger, error)

Application scans the application and builds a swagger spec based on the information from the code files. When there are includes provided, only those files are considered for the initial discovery. Similarly the excludes will exclude an item from initial discovery through scanning for annotations. When something in the discovered items requires a type that is contained in the includes or excludes it will still be in the spec.

Types

type Opts

type Opts struct {
	BasePath    string
	Input       *spec.Swagger
	ScanModels  bool
	BuildTags   string
	Include     []string
	Exclude     []string
	IncludeTags []string
	ExcludeTags []string
}

The Opts for the application scanner.