generator

package
v0.0.0-...-220a68f Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2017 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package generator provides the code generation library for go-swagger

The general idea is that you should rarely see interface{} in the generated code. You get a complete representation of a swagger document in somewhat idiomatic go.

To do so there is set of mapping patterns that are applied to a spec to go types: 

defintion of primitive => type alias/name
defintion of array => type alias/name
definition of map => type alias/name
definition of object with properties => struct
definition of ref => type alias/name
object with only additional properties => map[string]T
object with additional properties and properties => custom serializer
schema with schema array in items => tuple (struct with properties, custom serializer)
schema with all of => struct
  * all of schema with ref => embedded value
  * all of schema with properties => properties are included in struct
  * adding an all of schema with just "x-isnullable": true or "x-nullable": true turns
  the schema into a pointer when there are only other extension properties provided

A property on a definition is a pointer when: 

it is a object schema (struct)
it has x-nullable or x-isnullable as vendor extension
it is a primitive where the zero value is valid but would fail validation otherwise
  strings minLength > 0 or required results in non-pointer
  numbers min > 0, max < 0 and min < max

JSONSchema and by extension swagger allow for items that have a fixed size array with schema's describing the items at each index. This can be combined with additional items to form some kind of tuple with varargs. To map this to go it creates a struct that has fixed names and a custom json serializer.

The code that is generated also gets the doc comments that are used by the scanner to generate a spec from go code. So that after generation you should be able to reverse generate a spec from the code that was generated by your spec.

It should be equivalent to the original spec but might miss some default values and examples.

Index

Constants

This section is empty.

Variables

View Source 
var Debug = os.Getenv("DEBUG") != ""

Debug when the env var DEBUG is not empty the generators will be very noisy about what they are doing

View Source 
var FuncMap template.FuncMap = map[string]interface{}{
	"pascalize": pascalize,
	"camelize":  swag.ToJSONName,
	"varname":   golang.MangleVarName,
	"humanize":  swag.ToHumanNameLower,
	"snakize":   swag.ToFileName,
	"dasherize": swag.ToCommandName,
	"pluralizeFirstWord": func(arg string) string {
		sentence := strings.Split(arg, " ")
		if len(sentence) == 1 {
			return inflect.Pluralize(arg)
		}

		return inflect.Pluralize(sentence[0]) + " " + strings.Join(sentence[1:], " ")
	},
	"json":       asJSON,
	"prettyjson": asPrettyJSON,
	"hasInsecure": func(arg []string) bool {
		return swag.ContainsStringsCI(arg, "http") || swag.ContainsStringsCI(arg, "ws")
	},
	"hasSecure": func(arg []string) bool {
		return swag.ContainsStringsCI(arg, "https") || swag.ContainsStringsCI(arg, "wss")
	},
	"stripPackage": func(str, pkg string) string {
		parts := strings.Split(str, ".")
		strlen := len(parts)
		if strlen > 0 {
			return parts[strlen-1]
		}
		return str
	},
	"dropPackage": func(str string) string {
		parts := strings.Split(str, ".")
		strlen := len(parts)
		if strlen > 0 {
			return parts[strlen-1]
		}
		return str
	},
	"upper": func(str string) string {
		return strings.ToUpper(str)
	},
	"contains": func(coll []string, arg string) bool {
		for _, v := range coll {
			if v == arg {
				return true
			}
		}
		return false
	},
	"padSurround": func(entry, padWith string, i, ln int) string {
		var res []string
		if i > 0 {
			for j := 0; j < i; j++ {
				res = append(res, padWith)
			}
		}
		res = append(res, entry)
		tot := ln - i - 1
		for j := 0; j < tot; j++ {
			res = append(res, padWith)
		}
		return strings.Join(res, ",")
	},
	"joinFilePath": filepath.Join,
	"comment": func(str string) string {
		lines := strings.Split(str, "\n")
		return strings.Join(lines, "\n// ")
	},
	"inspect":   pretty.Sprint,
	"cleanPath": path.Clean,
}

FuncMap is a map with default functions for use n the templates. These are available in every template

Functions

func AddFile 

func AddFile(name, data string) error

AddFile adds a file to the default repository. It will create a new template based on the filename. It trims the .gotmpl from the end and converts the name using swag.ToJSONName. This will strip directory separators and Camelcase the next letter. e.g validation/primitive.gotmpl will become validationPrimitive

If the file contains a definition for a template that is protected the whole file will not be added

func Asset 

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir 

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy: 

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo 

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames 

func AssetNames() []string

AssetNames returns the names of the assets.

func DefaultSectionOpts 

func DefaultSectionOpts(gen *GenOpts, client bool)

DefaultSectionOpts for a given opts, this is used when no config file is passed and uses the embedded templates when no local override can be found

func GenerateClient 

func GenerateClient(name string, modelNames, operationIDs []string, opts *GenOpts) error

GenerateClient generates a client library for a swagger spec document.

func GenerateDefinition 

func GenerateDefinition(modelNames []string, opts *GenOpts) error

GenerateDefinition generates a model file for a schema definition.

func GenerateServer 

func GenerateServer(name string, modelNames, operationIDs []string, opts *GenOpts) error

GenerateServer generates a server application

func GenerateServerOperation 

func GenerateServerOperation(operationNames []string, opts *GenOpts) error

GenerateServerOperation generates a parameter model, parameter validator, http handler implementations for a given operation It also generates an operation handler interface that uses the parameter model for handling a valid request. Allows for specifying a list of tags to include only certain tags for the generation

func GenerateSupport 

func GenerateSupport(name string, modelNames, operationIDs []string, opts *GenOpts) error

GenerateSupport generates the supporting files for an API

func MustAsset 

func MustAsset(name string) []byte

MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.

func ReadConfig 

func ReadConfig(fpath string) (*viper.Viper, error)

ReadConfig at the specified path, when no path is specified it will look into the current directory and load a .swagger.{yml,json,hcl,toml,properties} file Returns a viper config or an error

func RestoreAsset 

func RestoreAsset(dir, name string) error

RestoreAsset restores an asset under the given directory

func RestoreAssets 

func RestoreAssets(dir, name string) error

RestoreAssets restores an asset under the given directory recursively

Types

type GenApp 

type GenApp struct {
	APIPackage          string
	Package             string
	ReceiverName        string
	Name                string
	Principal           string
	DefaultConsumes     string
	DefaultProduces     string
	Host                string
	BasePath            string
	Info                *spec.Info
	ExternalDocs        *spec.ExternalDocumentation
	Imports             map[string]string
	DefaultImports      []string
	Schemes             []string
	ExtraSchemes        []string
	Consumes            GenSerGroups
	Produces            GenSerGroups
	SecurityDefinitions []GenSecurityScheme
	Models              []GenDefinition
	Operations          GenOperations
	OperationGroups     GenOperationGroups
	SwaggerJSON         string
	ExcludeSpec         bool
	WithContext         bool
	GenOpts             *GenOpts
}

GenApp represents all the meta data needed to generate an application from a swagger spec

func (*GenApp) UseGoStructFlags 

func (g *GenApp) UseGoStructFlags() bool

UseGoStructFlags returns true when no strategy is specified or it is set to "go-flags"

func (*GenApp) UseIntermediateMode 

func (g *GenApp) UseIntermediateMode() bool

UseIntermediateMode for https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29

func (*GenApp) UseModernMode 

func (g *GenApp) UseModernMode() bool

UseModernMode for https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility

func (*GenApp) UsePFlags 

func (g *GenApp) UsePFlags() bool

UsePFlags returns true when the flag strategy is set to pflag

type GenDefinition 

type GenDefinition struct {
	GenSchema
	Package        string
	Imports        map[string]string
	DefaultImports []string
	ExtraSchemas   []GenSchema
	DependsOn      []string
}

GenDefinition contains all the properties to generate a definition from a swagger spec

func (*GenDefinition) Zero 

func (rt *GenDefinition) Zero() string

type GenHeader 

type GenHeader struct {
	Package      string
	ReceiverName string
	IndexVar     string

	ID              string
	Name            string
	Path            string
	ValueExpression string

	Title       string
	Description string
	Default     interface{}
	HasDefault  bool

	CollectionFormat string

	Child  *GenItems
	Parent *GenItems

	Converter string
	Formatter string

	ZeroValue string
	// contains filtered or unexported fields
}

GenHeader represents a header on a response for code generation

func (*GenHeader) Zero 

func (rt *GenHeader) Zero() string

type GenHeaders 

type GenHeaders []GenHeader

GenHeaders is a sorted collection of headers for codegen

func (GenHeaders) Len 

func (g GenHeaders) Len() int

func (GenHeaders) Less 

func (g GenHeaders) Less(i, j int) bool

func (GenHeaders) Swap 

func (g GenHeaders) Swap(i, j int)

type GenItems 

type GenItems struct {
	Name             string
	Path             string
	ValueExpression  string
	CollectionFormat string
	Child            *GenItems
	Parent           *GenItems
	Converter        string
	Formatter        string

	Location string
	IndexVar string
	// contains filtered or unexported fields
}

GenItems represents the collection items for a collection parameter

func (*GenItems) Zero 

func (rt *GenItems) Zero() string

type GenOperation 

type GenOperation struct {
	Package      string
	ReceiverName string
	Name         string
	Summary      string
	Description  string
	Method       string
	Path         string
	BasePath     string
	Tags         []string
	RootPackage  string

	Imports        map[string]string
	DefaultImports []string
	ExtraSchemas   []GenSchema

	Authorized          bool
	Security            []analysis.SecurityRequirement
	SecurityDefinitions map[string]spec.SecurityScheme
	Principal           string

	SuccessResponse  *GenResponse
	SuccessResponses []GenResponse
	Responses        GenStatusCodeResponses
	DefaultResponse  *GenResponse

	Params               GenParameters
	QueryParams          GenParameters
	PathParams           GenParameters
	HeaderParams         GenParameters
	FormParams           GenParameters
	HasQueryParams       bool
	HasFormParams        bool
	HasFormValueParams   bool
	HasFileParams        bool
	HasStreamingResponse bool

	Schemes            []string
	ExtraSchemes       []string
	ProducesMediaTypes []string
	ConsumesMediaTypes []string
	WithContext        bool
	TimeoutName        string

	Extensions map[string]interface{}
}

GenOperation represents an operation for code generation

type GenOperationGroup 

type GenOperationGroup struct {
	Name       string
	Operations GenOperations

	Summary        string
	Description    string
	Imports        map[string]string
	DefaultImports []string
	RootPackage    string
	WithContext    bool
}

GenOperationGroup represents a named (tagged) group of operations

type GenOperationGroups 

type GenOperationGroups []GenOperationGroup

GenOperationGroups is a sorted collection of operation groups

func (GenOperationGroups) Len 

func (g GenOperationGroups) Len() int

func (GenOperationGroups) Less 

func (g GenOperationGroups) Less(i, j int) bool

func (GenOperationGroups) Swap 

func (g GenOperationGroups) Swap(i, j int)

type GenOperations 

type GenOperations []GenOperation

GenOperations represents a list of operations to generate this implements a sort by operation id

func (GenOperations) Len 

func (g GenOperations) Len() int

func (GenOperations) Less 

func (g GenOperations) Less(i, j int) bool

func (GenOperations) Swap 

func (g GenOperations) Swap(i, j int)

type GenOpts 

type GenOpts struct {
	IncludeModel      bool
	IncludeValidator  bool
	IncludeHandler    bool
	IncludeParameters bool
	IncludeResponses  bool
	IncludeURLBuilder bool
	IncludeMain       bool
	IncludeSupport    bool
	ExcludeSpec       bool
	DumpData          bool
	WithContext       bool
	ValidateSpec      bool

	Spec              string
	APIPackage        string
	ModelPackage      string
	ServerPackage     string
	ClientPackage     string
	Principal         string
	Target            string
	Sections          SectionOpts
	LanguageOpts      *LanguageOpts
	TypeMapping       map[string]string
	Imports           map[string]string
	DefaultScheme     string
	DefaultProduces   string
	DefaultConsumes   string
	TemplateDir       string
	Operations        []string
	Models            []string
	Tags              []string
	Name              string
	FlagStrategy      string
	CompatibilityMode string
	ExistingModels    string
	// contains filtered or unexported fields
}

GenOpts the options for the generator

func (*GenOpts) EnsureDefaults 

func (g *GenOpts) EnsureDefaults(client bool) error

EnsureDefaults for these gen opts

func (*GenOpts) SpecPath 

func (g *GenOpts) SpecPath() string

SpecPath returns the path to the spec relative to the server package

func (*GenOpts) TargetPath 

func (g *GenOpts) TargetPath() string

TargetPath returns the target path relative to the server package

type GenParameter 

type GenParameter struct {
	ID              string
	Name            string
	ModelsPackage   string
	Path            string
	ValueExpression string
	IndexVar        string
	ReceiverName    string
	Location        string
	Title           string
	Description     string
	Converter       string
	Formatter       string

	Schema *GenSchema

	CollectionFormat string

	Child  *GenItems
	Parent *GenItems

	BodyParam *GenParameter

	Default         interface{}
	HasDefault      bool
	ZeroValue       string
	AllowEmptyValue bool

	Extensions map[string]interface{}
	// contains filtered or unexported fields
}

GenParameter is used to represent a parameter or a header for code generation.

func (*GenParameter) IsBodyParam 

func (g *GenParameter) IsBodyParam() bool

IsBodyParam returns true when this parameter is a body param

func (*GenParameter) IsFileParam 

func (g *GenParameter) IsFileParam() bool

IsFileParam returns true when this parameter is a file param

func (*GenParameter) IsFormParam 

func (g *GenParameter) IsFormParam() bool

IsFormParam returns true when this parameter is a form param

func (*GenParameter) IsHeaderParam 

func (g *GenParameter) IsHeaderParam() bool

IsHeaderParam returns true when this parameter is a header param

func (*GenParameter) IsPathParam 

func (g *GenParameter) IsPathParam() bool

IsPathParam returns true when this parameter is a path param

func (*GenParameter) IsQueryParam 

func (g *GenParameter) IsQueryParam() bool

IsQueryParam returns true when this parameter is a query param

func (*GenParameter) Zero 

func (rt *GenParameter) Zero() string

type GenParameters 

type GenParameters []GenParameter

GenParameters represents a sorted parameter collection

func (GenParameters) Len 

func (g GenParameters) Len() int

func (GenParameters) Less 

func (g GenParameters) Less(i, j int) bool

func (GenParameters) Swap 

func (g GenParameters) Swap(i, j int)

type GenResponse 

type GenResponse struct {
	Package       string
	ModelsPackage string
	ReceiverName  string
	Name          string
	Description   string

	IsSuccess bool

	Code               int
	Method             string
	Path               string
	Headers            GenHeaders
	Schema             *GenSchema
	AllowsForStreaming bool

	Imports        map[string]string
	DefaultImports []string

	Extensions map[string]interface{}
}

GenResponse represents a response object for code generation

type GenSchema 

type GenSchema struct {
	Example                 string
	OriginalName            string
	Name                    string
	Suffix                  string
	Path                    string
	ValueExpression         string
	IndexVar                string
	KeyVar                  string
	Title                   string
	Description             string
	Location                string
	ReceiverName            string
	Items                   *GenSchema
	AllowsAdditionalItems   bool
	HasAdditionalItems      bool
	AdditionalItems         *GenSchema
	Object                  *GenSchema
	XMLName                 string
	CustomTag               string
	Properties              GenSchemaList
	AllOf                   []GenSchema
	HasAdditionalProperties bool
	IsAdditionalProperties  bool
	AdditionalProperties    *GenSchema
	ReadOnly                bool
	IsVirtual               bool
	IsBaseType              bool
	HasBaseType             bool
	IsSubType               bool
	IsExported              bool
	DiscriminatorField      string
	DiscriminatorValue      string
	Discriminates           map[string]string
	Parents                 []string
	IncludeValidator        bool
	IncludeModel            bool
	Default                 interface{}
	// contains filtered or unexported fields
}

GenSchema contains all the information needed to generate the code for a schema

func (*GenSchema) Zero 

func (rt *GenSchema) Zero() string

type GenSchemaList 

type GenSchemaList []GenSchema

GenSchemaList is a list of schemas for generation.

It can be sorted by name to get a stable struct layout for version control and such

func (GenSchemaList) Len 

func (g GenSchemaList) Len() int

func (GenSchemaList) Less 

func (g GenSchemaList) Less(i, j int) bool

func (GenSchemaList) Swap 

func (g GenSchemaList) Swap(i, j int)

type GenSecurityScheme 

type GenSecurityScheme struct {
	AppName      string
	ID           string
	Name         string
	ReceiverName string
	IsBasicAuth  bool
	IsAPIKeyAuth bool
	IsOAuth2     bool
	Scopes       []string
	Source       string
	Principal    string
}

GenSecurityScheme represents a security scheme for code generation

type GenSecuritySchemes 

type GenSecuritySchemes []GenSecurityScheme

GenSecuritySchemes sorted representation of serializers

func (GenSecuritySchemes) Len 

func (g GenSecuritySchemes) Len() int

func (GenSecuritySchemes) Less 

func (g GenSecuritySchemes) Less(i, j int) bool

func (GenSecuritySchemes) Swap 

func (g GenSecuritySchemes) Swap(i, j int)

type GenSerGroup 

type GenSerGroup struct {
	ReceiverName   string
	AppName        string
	Name           string
	MediaType      string
	Implementation string
	AllSerializers GenSerializers
}

GenSerGroup represents a group of serializers, most likely this is a media type to a list of prioritized serializers.

type GenSerGroups 

type GenSerGroups []GenSerGroup

GenSerGroups sorted representation of serializer groups

func (GenSerGroups) Len 

func (g GenSerGroups) Len() int

func (GenSerGroups) Less 

func (g GenSerGroups) Less(i, j int) bool

func (GenSerGroups) Swap 

func (g GenSerGroups) Swap(i, j int)

type GenSerializer 

type GenSerializer struct {
	ReceiverName   string
	AppName        string
	Name           string
	MediaType      string
	Implementation string
}

GenSerializer represents a single serializer for a particular media type

type GenSerializers 

type GenSerializers []GenSerializer

GenSerializers sorted representation of serializers

func (GenSerializers) Len 

func (g GenSerializers) Len() int

func (GenSerializers) Less 

func (g GenSerializers) Less(i, j int) bool

func (GenSerializers) Swap 

func (g GenSerializers) Swap(i, j int)

type GenStatusCodeResponses 

type GenStatusCodeResponses []GenResponse

GenStatusCodeResponses a container for status code responses

func (GenStatusCodeResponses) Len 

func (g GenStatusCodeResponses) Len() int

func (GenStatusCodeResponses) Less 

func (g GenStatusCodeResponses) Less(i, j int) bool

func (GenStatusCodeResponses) MarshalJSON 

func (g GenStatusCodeResponses) MarshalJSON() ([]byte, error)

MarshalJSON marshals these responses to json

func (GenStatusCodeResponses) Swap 

func (g GenStatusCodeResponses) Swap(i, j int)

func (*GenStatusCodeResponses) UnmarshalJSON 

func (g *GenStatusCodeResponses) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals this GenStatusCodeResponses from json

type LanguageConfig 

type LanguageConfig map[string]LanguageDefinition

LanguageConfig structure that is obtained from parsing a config file

type LanguageDefinition 

type LanguageDefinition struct {
	Layout SectionOpts `mapstructure:"layout"`
}

LanguageDefinition in the configuration file.

func (*LanguageDefinition) ConfigureOpts 

func (d *LanguageDefinition) ConfigureOpts(opts *GenOpts) error

ConfigureOpts for generation

type LanguageOpts 

type LanguageOpts struct {
	ReservedWords []string
	// contains filtered or unexported fields
}

LanguageOpts to describe a language to the code generator

func GoLangOpts 

func GoLangOpts() *LanguageOpts

GoLangOpts for rendering items as golang code

func (*LanguageOpts) FormatContent 

func (l *LanguageOpts) FormatContent(name string, content []byte) ([]byte, error)

FormatContent formats a file with a language specific formatter

func (*LanguageOpts) Init 

func (l *LanguageOpts) Init()

Init the language option

func (*LanguageOpts) MangleName 

func (l *LanguageOpts) MangleName(name, suffix string) string

MangleName makes sure a reserved word gets a safe name

func (*LanguageOpts) MangleVarName 

func (l *LanguageOpts) MangleVarName(name string) string

MangleVarName makes sure a reserved word gets a safe name

type Repository 

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

Repository is the repository for the generator templates.

func NewRepository 

func NewRepository(funcs template.FuncMap) *Repository

NewRepository creates a new template repository with the provided functions defined

func (*Repository) AddFile 

func (t *Repository) AddFile(name, data string) error

AddFile adds a file to the repository. It will create a new template based on the filename. It trims the .gotmpl from the end and converts the name using swag.ToJSONName. This will strip directory separators and Camelcase the next letter. e.g validation/primitive.gotmpl will become validationPrimitive

If the file contains a definition for a template that is protected the whole file will not be added

func (*Repository) DumpTemplates 

func (t *Repository) DumpTemplates()

DumpTemplates prints out a dump of all the defined templates, where they are defined and what their dependencies are.

func (*Repository) Get 

func (t *Repository) Get(name string) (*template.Template, error)

Get will return the named template from the repository, ensuring that all dependent templates are loaded. It will return an error if a dependent template is not defined in the repository.

func (*Repository) LoadDefaults 

func (t *Repository) LoadDefaults()

LoadDefaults will load the embedded templates

func (*Repository) LoadDir 

func (t *Repository) LoadDir(templatePath string) error

LoadDir will walk the specified path and add each .gotmpl file it finds to the repository

func (*Repository) MustGet 

func (t *Repository) MustGet(name string) *template.Template

MustGet a template by name, panics when fails

type SectionOpts 

type SectionOpts struct {
	Application     []TemplateOpts `mapstructure:"application"`
	Operations      []TemplateOpts `mapstructure:"operations"`
	OperationGroups []TemplateOpts `mapstructure:"operation_groups"`
	Models          []TemplateOpts `mapstructure:"models"`
}

SectionOpts allows for specifying options to customize the templates used for generation

type TemplateOpts 

type TemplateOpts struct {
	Name       string `mapstructure:"name"`
	Source     string `mapstructure:"source"`
	Target     string `mapstructure:"target"`
	FileName   string `mapstructure:"file_name"`
	SkipExists bool   `mapstructure:"skip_exists"`
	SkipFormat bool   `mapstructure:"skip_format"`
}

TemplateOpts allows

Source Files

View all Source files
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.