generator

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 turns the schema into a pointer
    when there are only other extension properties provided

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

• Variables
• func GenerateDefinition(includeModel, includeValidator bool, opts GenOpts) error
• func GenerateServerOperation(includeHandler, includeParameters bool, opts GenOpts) error
• type GenDefinition
• type GenHeader
• type GenItems
• type GenOperation
• type GenOperationGroup
• type GenOpts
• type GenParameter
  • func (g *GenParameter) IsBodyParam() bool
  • func (g *GenParameter) IsFileParam() bool
  • func (g *GenParameter) IsFormParam() bool
  • func (g *GenParameter) IsHeaderParam() bool
  • func (g *GenParameter) IsPathParam() bool
  • func (g *GenParameter) IsQueryParam() bool
• type GenResponse
• type GenSchema
• type GenSchemaList
  • func (g GenSchemaList) Len() int
  • func (g GenSchemaList) Less(i, j int) bool
  • func (g GenSchemaList) Swap(i, j int)
• type Generator
  • func NewGenerator() *Generator

Variables

var Statuses = map[int]string{
	100: "Continue",
	101: "Switching Protocols",
	102: "Processing",
	103: "Checkpoint",
	122: "URI too long",
	200: "OK",
	201: "Created",
	202: "Accepted",
	203: "Request Processed",
	204: "No Content",
	205: "Reset Content",
	206: "Partial Content",
	207: "Mutli-Status",
	208: "Already Reported",
	226: "IM Used",
	300: "Multiple Choices",
	301: "Moved Permanently",
	302: "Found",
	303: "See Other",
	304: "Not Modified",
	305: "Use Proxy",
	306: "Switch Proxy",
	307: "Temporary Redirect",
	308: "Permanent Redirect",
	400: "Bad Request",
	401: "Unauthorized",
	402: "Payment Required",
	403: "Forbidden",
	404: "Not Found",
	405: "Method Not Allowed",
	406: "Not Acceptable",
	407: "Proxy Authentication Required",
	408: "Request Timeout",
	409: "Conflict",
	410: "Gone",
	411: "Length Required",
	412: "Precondition Failed",
	413: "Request Entity Too Large",
	414: "Request-URI Too Long",
	415: "Unsupported Media Type",
	416: "Request Range Not Satisfiable",
	417: "Expectation Failed",
	418: "I'm a teapot",
	420: "Enhance Your Calm",
	422: "Unprocessable Entity",
	423: "Locked",
	424: "Failed Dependency",
	426: "Upgrade Required",
	428: "Precondition Required",
	429: "Too Many Requests",
	431: "Request Header Fields Too Large",
	444: "No Response",
	449: "Retry With",
	450: "Blocked by Windows Parental Controls",
	451: "Wrong Exchange Server",
	499: "Client Closed Request",
	500: "Internal Server Error",
	501: "Not Implemented",
	502: "Bad Gateway",
	503: "Service Unavailable",
	504: "Gateway Timeout",
	505: "HTTP Version Not Supported",
	506: "Variant Also Negotiates",
	507: "Insufficient Storage",
	508: "Loop Detected",
	509: "Bandwidth Limit Exceeded",
	510: "Not Extended",
	511: "Network Authentication Required",
	598: "Network read timeout error",
	599: "Network connect timeout error",
}

Statuses lists the most common HTTP status codes to default message taken from http://status.es

Functions

func GenerateDefinition

func GenerateDefinition(includeModel, includeValidator bool, opts GenOpts) error

GenerateDefinition generates a model file for a schema defintion.

func GenerateServerOperation

func GenerateServerOperation(includeHandler, includeParameters bool, 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

Types

type GenDefinition

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

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

type GenHeader

type GenHeader struct {
	Package      string
	ReceiverName string

	Name string
	Path string

	Title       string
	Description string

	Converter string
	Formatter string
	// contains filtered or unexported fields
}

GenHeader represents a header on a response for code generation

type GenItems

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

	Location string
	// contains filtered or unexported fields
}

GenItems represents the collection items for a collection parameter

type GenOperation

type GenOperation struct {
	Package      string
	ReceiverName string
	Name         string
	Summary      string
	Description  string

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

	Authorized bool
	Principal  string

	SuccessResponse *GenResponse
	Responses       map[int]GenResponse
	DefaultResponse *GenResponse

	Params         []GenParameter
	QueryParams    []GenParameter
	PathParams     []GenParameter
	HeaderParams   []GenParameter
	FormParams     []GenParameter
	HasQueryParams bool
	HasFormParams  bool
	HasFileParams  bool
}

GenOperation represents an operation for code generation

type GenOperationGroup

type GenOperationGroup struct {
	Name       string
	Operations []GenOperation

	Summary        string
	Description    string
	Imports        map[string]string
	DefaultImports []string
}

GenOperationGroup represents a named (tagged) group of operations

type GenOpts

type GenOpts struct {
	Spec          string
	APIPackage    string
	ModelPackage  string
	ServerPackage string
	ClientPackage string
	Principal     string
	Target        string
	TypeMapping   map[string]string
	Imports       map[string]string
	DumpData      bool
}

GenOpts the options for the generator

type GenParameter

type GenParameter struct {
	Name            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{}
	Enum    []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

type GenResponse

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

	IsSuccess bool

	Headers []GenHeader
	Schema  *GenSchema

	Imports        map[string]string
	DefaultImports []string
}

GenResponse represents a response object for code generation

type GenSchema

type GenSchema struct {
	Example                 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
	Properties              GenSchemaList
	AllOf                   []GenSchema
	HasAdditionalProperties bool
	IsAdditionalProperties  bool
	AdditionalProperties    *GenSchema
	ReadOnly                bool
	IsVirtual               bool
	// contains filtered or unexported fields
}

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

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 Generator

type Generator struct {
	*bytes.Buffer
}

Generator is the type whose methods generate the output, stored in the associated response structure.

func NewGenerator

func NewGenerator() *Generator

New creates a new generator and allocates the request and response protobufs.