codegen

package
v1.3.7 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2022 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Copyright 2019 DeepMap, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2019 DeepMap, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2019 DeepMap, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2019 DeepMap, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

This section is empty.

Variables

View Source 
var TemplateFunctions = template.FuncMap{
	"genParamArgs":               genParamArgs,
	"genParamTypes":              genParamTypes,
	"genParamNames":              genParamNames,
	"genParamFmtString":          genParamFmtString,
	"swaggerUriToEchoUri":        SwaggerUriToEchoUri,
	"swaggerUriToChiUri":         SwaggerUriToChiUri,
	"lcFirst":                    LowercaseFirstCharacter,
	"ucFirst":                    UppercaseFirstCharacter,
	"camelCase":                  ToCamelCase,
	"genResponsePayload":         genResponsePayload,
	"genResponseTypeName":        genResponseTypeName,
	"genResponseUnmarshal":       genResponseUnmarshal,
	"getResponseTypeDefinitions": getResponseTypeDefinitions,
	"toStringArray":              toStringArray,
	"lower":                      strings.ToLower,
	"title":                      strings.Title,
	"stripNewLines":              stripNewLines,
}

This function map is passed to the template engine, and we can call each function here by keyName from the template code.

View Source 
var TypeMappings = map[string]string{}

Functions

func GenFieldsFromProperties 

func GenFieldsFromProperties(props []Property) []string

Given a list of schema descriptors, produce corresponding field names with JSON annotations

func GenStructFromAllOf 

func GenStructFromAllOf(allOf []*openapi3.SchemaRef, path []string) (string, error)

This function generates an object that is the union of the objects in the input array. In the case of Ref objects, we use an embedded struct, otherwise, we inline the fields.

func GenStructFromSchema 

func GenStructFromSchema(schema Schema) string

func Generate 

func Generate(swagger *openapi3.Swagger, packageName string, opts Options) (string, error)

Uses the Go templating engine to generate all of our server wrappers from the descriptions we've built up above from the schema objects. opts defines

func GenerateAdditionalPropertyBoilerplate 

func GenerateAdditionalPropertyBoilerplate(t *template.Template, typeDefs []TypeDefinition) (string, error)

Generate all the glue code which provides the API for interacting with additional properties and JSON-ification

func GenerateBodyDefinitions 

func GenerateBodyDefinitions(operationID string, bodyOrRef *openapi3.RequestBodyRef) ([]RequestBodyDefinition, []TypeDefinition, error)

This function turns the Swagger body definitions into a list of our body definitions which will be used for code generation.

func GenerateChiServer 

func GenerateChiServer(t *template.Template, operations []OperationDefinition) (string, error)

GenerateChiServer This function generates all the go code for the ServerInterface as well as all the wrapper functions around our handlers.

func GenerateClient 

func GenerateClient(t *template.Template, ops []OperationDefinition) (string, error)

Uses the template engine to generate the function which registers our wrappers as Echo path handlers.

func GenerateClientWithResponses 

func GenerateClientWithResponses(t *template.Template, ops []OperationDefinition) (string, error)

This generates a client which extends the basic client which does response unmarshaling.

func GenerateEchoServer 

func GenerateEchoServer(t *template.Template, operations []OperationDefinition) (string, error)

GenerateEchoServer This function generates all the go code for the ServerInterface as well as all the wrapper functions around our handlers.

func GenerateImports 

func GenerateImports(t *template.Template, imports []string, packageName string) (string, error)

Generate our import statements and package definition.

func GenerateInlinedSpec 

func GenerateInlinedSpec(t *template.Template, swagger *openapi3.Swagger) (string, error)

This generates a gzipped, base64 encoded JSON representation of the swagger definition, which we embed inside the generated code.

func GenerateRegistration 

func GenerateRegistration(t *template.Template, ops []OperationDefinition) (string, error)

Uses the template engine to generate the function which registers our wrappers as Echo path handlers.

func GenerateServerInterface 

func GenerateServerInterface(t *template.Template, ops []OperationDefinition) (string, error)

Uses the template engine to generate the server interface

func GenerateTypeDefinitions 

func GenerateTypeDefinitions(t *template.Template, swagger *openapi3.Swagger, ops []OperationDefinition) (string, error)

func GenerateTypes 

func GenerateTypes(t *template.Template, types []TypeDefinition) (string, error)

Helper function to pass a bunch of types to the template engine, and buffer its output into a string.

func GenerateTypesForOperations 

func GenerateTypesForOperations(t *template.Template, ops []OperationDefinition) (string, error)

Generates code for all types produced

func GenerateWrappers 

func GenerateWrappers(t *template.Template, ops []OperationDefinition) (string, error)

Uses the template engine to generate all the wrappers which wrap our simple interface functions and perform marshallin/unmarshalling from HTTP request objects.

func IsGoKeyword 

func IsGoKeyword(str string) bool

Returns whether the given string is a go keyword

func LowercaseFirstCharacter 

func LowercaseFirstCharacter(str string) string

Same as above, except lower case

func OrderedParamsFromUri 

func OrderedParamsFromUri(uri string) []string

Returns the argument names, in order, in a given URI string, so for /path/{param1}/{.param2*}/{?param3}, it would return param1, param2, param3

func PathToTypeName 

func PathToTypeName(path []string) string

This converts a path, like Object/field1/nestedField into a go type name.

func PropertiesEqual 

func PropertiesEqual(a, b Property) bool

func RefPathToGoType 

func RefPathToGoType(refPath string) (string, error)

This function takes a $ref value and converts it to a Go typename. #/components/schemas/Foo -> Foo #/components/parameters/Bar -> Bar #/components/responses/Baz -> Baz Remote components (document.json#/Foo) are not yet supported URL components (http://deepmap.com/schemas/document.json#Foo) are not yet supported We only support flat components for now, so no components in a schema under components.

func ReplacePathParamsWithStr 

func ReplacePathParamsWithStr(uri string) string

Replaces path parameters with %s

func SanitizeCode 

func SanitizeCode(goCode string) string

SanitizeCode runs sanitizers across the generated Go code to ensure the generated code will be able to compile.

func SchemaHasAdditionalProperties 

func SchemaHasAdditionalProperties(schema *openapi3.Schema) bool

According to the spec, additionalProperties may be true, false, or a schema. If not present, true is implied. If it's a schema, true is implied. If it's false, no additional properties are allowed. We're going to act a little differently, in that if you want additionalProperties code to be generated, you must specify an additionalProperties type If additionalProperties it true/false, this field will be non-nil.

func SchemaNameToTypeName 

func SchemaNameToTypeName(name string) string

Converts a Schema name to a valid Go type name. It converts to camel case, and makes sure the name is valid in Go

func SortedContentKeys 

func SortedContentKeys(dict openapi3.Content) []string

This returns Content dictionary keys in sorted order

func SortedOperationsKeys 

func SortedOperationsKeys(dict map[string]*openapi3.Operation) []string

This function returns Operation dictionary keys in sorted order

func SortedParameterKeys 

func SortedParameterKeys(dict map[string]*openapi3.ParameterRef) []string

This returns sorted keys for a ParameterRef dict

func SortedPathsKeys 

func SortedPathsKeys(dict openapi3.Paths) []string

This function is the same as above, except it sorts the keys for a Paths dictionary.

func SortedRequestBodyKeys 

func SortedRequestBodyKeys(dict map[string]*openapi3.RequestBodyRef) []string

func SortedResponsesKeys 

func SortedResponsesKeys(dict openapi3.Responses) []string

This function returns Responses dictionary keys in sorted order

func SortedSchemaKeys 

func SortedSchemaKeys(dict map[string]*openapi3.SchemaRef) []string

This function returns the keys of the given SchemaRef dictionary in sorted order, since Golang scrambles dictionary keys

func SortedStringKeys 

func SortedStringKeys(dict map[string]string) []string

This returns string map keys in sorted order

func StringInArray 

func StringInArray(str string, array []string) bool

This function checks whether the specified string is present in an array of strings

func StringToGoComment 

func StringToGoComment(in string) string

StringToGoComment renders a possible multi-line string as a valid Go-Comment. Each line is prefixed as a comment.

func SwaggerUriToChiUri 

func SwaggerUriToChiUri(uri string) string

This function converts a swagger style path URI with parameters to a Chi compatible path URI. We need to replace all of Swagger parameters with "{param}". Valid input parameters are: 

{param}
{param*}
{.param}
{.param*}
{;param}
{;param*}
{?param}
{?param*}

func SwaggerUriToEchoUri 

func SwaggerUriToEchoUri(uri string) string

This function converts a swagger style path URI with parameters to a Echo compatible path URI. We need to replace all of Swagger parameters with ":param". Valid input parameters are: 

{param}
{param*}
{.param}
{.param*}
{;param}
{;param*}
{?param}
{?param*}

func ToCamelCase 

func ToCamelCase(str string) string

This function will convert query-arg style strings to CamelCase. We will use `., -, +, :, ;, _, ~, ' ', (, ), {, }, [, ]` as valid delimiters for words. So, "word.word-word+word:word;word_word~word word(word)word{word}[word]" would be converted to WordWordWordWordWordWordWordWordWordWordWordWordWord

func UppercaseFirstCharacter 

func UppercaseFirstCharacter(str string) string

Uppercase the first character in a string. This assumes UTF-8, so we have to be careful with unicode, don't treat it as a byte array.

Types

type FieldDescriptor 

type FieldDescriptor struct {
	Required bool   // Is the schema required? If not, we'll pass by pointer
	GoType   string // The Go type needed to represent the json type.
	GoName   string // The Go compatible type name for the type
	JsonName string // The json type name for the type
	IsRef    bool   // Is this schema a reference to predefined object?
}

type OperationDefinition 

type OperationDefinition struct {
	OperationId string // The operation_id description from Swagger, used to generate function names

	PathParams          []ParameterDefinition // Parameters in the path, eg, /path/:param
	HeaderParams        []ParameterDefinition // Parameters in HTTP headers
	QueryParams         []ParameterDefinition // Parameters in the query, /path?param
	CookieParams        []ParameterDefinition // Parameters in cookies
	TypeDefinitions     []TypeDefinition      // These are all the types we need to define for this operation
	SecurityDefinitions []SecurityDefinition  // These are the security providers
	BodyRequired        bool
	Bodies              []RequestBodyDefinition // The list of bodies for which to generate handlers.
	Summary             string                  // Summary string from Swagger, used to generate a comment
	Method              string                  // GET, POST, DELETE, etc.
	Path                string                  // The Swagger path for the operation, like /resource/{id}
	Spec                *openapi3.Operation
}

This structure describes an Operation

func OperationDefinitions 

func OperationDefinitions(swagger *openapi3.Swagger) ([]OperationDefinition, error)

OperationDefinitions returns all operations for a swagger definition.

func (*OperationDefinition) AllParams 

func (o *OperationDefinition) AllParams() []ParameterDefinition

Returns all parameters

func (*OperationDefinition) GetResponseTypeDefinitions 

func (o *OperationDefinition) GetResponseTypeDefinitions() ([]TypeDefinition, error)

Produces a list of type definitions for a given Operation for the response types which we know how to parse. These will be turned into fields on a response object for automatic deserialization of responses in the generated Client code. See "client-with-responses.tmpl".

func (*OperationDefinition) HasBody 

func (o *OperationDefinition) HasBody() bool

This is called by the template engine to determine whether to generate body marshaling code on the client. This is true for all body types, whether or not we generate types for them.

func (*OperationDefinition) Params 

func (o *OperationDefinition) Params() []ParameterDefinition

Returns the list of all parameters except Path parameters. Path parameters are handled differently from the rest, since they're mandatory.

func (*OperationDefinition) RequiresParamObject 

func (o *OperationDefinition) RequiresParamObject() bool

If we have parameters other than path parameters, they're bundled into an object. Returns true if we have any of those. This is used from the template engine.

func (*OperationDefinition) SummaryAsComment 

func (o *OperationDefinition) SummaryAsComment() string

This returns the Operations summary as a multi line comment

type Options 

type Options struct {
	GenerateChiServer  bool              // GenerateChiServer specifies whether to generate chi server boilerplate
	GenerateEchoServer bool              // GenerateEchoServer specifies whether to generate echo server boilerplate
	GenerateClient     bool              // GenerateClient specifies whether to generate client boilerplate
	GenerateTypes      bool              // GenerateTypes specifies whether to generate type definitions
	EmbedSpec          bool              // Whether to embed the swagger spec in the generated code
	SkipFmt            bool              // Whether to skip go fmt on the generated code
	IncludeTags        []string          // Only include operations that have one of these tags. Ignored when empty.
	ExcludeTags        []string          // Exclude operations that have one of these tags. Ignored when empty.
	UserTemplates      map[string]string // Override built-in templates from user-provided files
}

Options defines the optional code to generate.

type ParameterDefinition 

type ParameterDefinition struct {
	ParamName string // The original json parameter name, eg param_name
	In        string // Where the parameter is defined - path, header, cookie, query
	Required  bool   // Is this a required parameter?
	Spec      *openapi3.Parameter
	Schema    Schema
}

func DescribeParameters 

func DescribeParameters(params openapi3.Parameters, path []string) ([]ParameterDefinition, error)

This function walks the given parameters dictionary, and generates the above descriptors into a flat list. This makes it a lot easier to traverse the data in the template engine.

func FilterParameterDefinitionByType 

func FilterParameterDefinitionByType(params []ParameterDefinition, in string) []ParameterDefinition

This function returns the subset of the specified parameters which are of the specified type.

func SortParamsByPath 

func SortParamsByPath(path string, in []ParameterDefinition) ([]ParameterDefinition, error)

Reorders the given parameter definitions to match those in the path URI.

func (*ParameterDefinition) Explode 

func (pd *ParameterDefinition) Explode() bool

func (ParameterDefinition) GoName 

func (pd ParameterDefinition) GoName() string

func (ParameterDefinition) GoVariableName 

func (pd ParameterDefinition) GoVariableName() string

func (ParameterDefinition) IndirectOptional 

func (pd ParameterDefinition) IndirectOptional() bool

func (*ParameterDefinition) IsJson 

func (pd *ParameterDefinition) IsJson() bool

func (*ParameterDefinition) IsPassThrough 

func (pd *ParameterDefinition) IsPassThrough() bool

func (*ParameterDefinition) IsStyled 

func (pd *ParameterDefinition) IsStyled() bool

func (*ParameterDefinition) JsonTag 

func (pd *ParameterDefinition) JsonTag() string

Generate the JSON annotation to map GoType to json type name. If Parameter Foo is marshaled to json as "foo", this will create the annotation 'json:"foo"'

func (*ParameterDefinition) Style 

func (pd *ParameterDefinition) Style() string

func (ParameterDefinition) TypeDef 

func (pd ParameterDefinition) TypeDef() string

This function is here as an adapter after a large refactoring so that I don't have to update all the templates. It returns the type definition for a parameter, without the leading '*' for optional ones.

type ParameterDefinitions 

type ParameterDefinitions []ParameterDefinition

func (ParameterDefinitions) FindByName 

func (p ParameterDefinitions) FindByName(name string) *ParameterDefinition

type Property 

type Property struct {
	Description   string
	JsonFieldName string
	Schema        Schema
	Required      bool
}

func (Property) GoFieldName 

func (p Property) GoFieldName() string

func (Property) GoTypeDef 

func (p Property) GoTypeDef() string

type RequestBodyDefinition 

type RequestBodyDefinition struct {
	// Is this body required, or optional?
	Required bool

	// This is the schema describing this body
	Schema Schema

	// When we generate type names, we need a Tag for it, such as JSON, in
	// which case we will produce "JSONBody".
	NameTag string

	// This is the content type corresponding to the body, eg, application/json
	ContentType string

	// Whether this is the default body type. For an operation named OpFoo, we
	// will not add suffixes like OpFooJSONBody for this one.
	Default bool
}

This describes a request body

func (RequestBodyDefinition) CustomType 

func (r RequestBodyDefinition) CustomType() bool

Returns whether the body is a custom inline type, or pre-defined. This is poorly named, but it's here for compatibility reasons post-refactoring TODO: clean up the templates code, it can be simpler.

func (RequestBodyDefinition) Suffix 

func (r RequestBodyDefinition) Suffix() string

When we're generating multiple functions which relate to request bodies, this generates the suffix. Such as Operation DoFoo would be suffixed with DoFooWithXMLBody.

func (RequestBodyDefinition) TypeDef 

func (r RequestBodyDefinition) TypeDef() string

Returns the Go type definition for a request body

type Schema 

type Schema struct {
	GoType  string // The Go type needed to represent the schema
	RefType string // If the type has a type name, this is set

	Properties               []Property       // For an object, the fields with names
	HasAdditionalProperties  bool             // Whether we support additional properties
	AdditionalPropertiesType *Schema          // And if we do, their type
	AdditionalTypes          []TypeDefinition // We may need to generate auxiliary helper types, stored here

	SkipOptionalPointer bool // Some types don't need a * in front when they're optional
}

This describes a Schema, a type definition.

func GenerateGoSchema 

func GenerateGoSchema(sref *openapi3.SchemaRef, path []string) (Schema, error)

func MergeSchemas 

func MergeSchemas(allOf []*openapi3.SchemaRef, path []string) (Schema, error)

Merge all the fields in the schemas supplied into one giant schema.

func (Schema) GetAdditionalTypeDefs 

func (s Schema) GetAdditionalTypeDefs() []TypeDefinition

func (Schema) IsRef 

func (s Schema) IsRef() bool

func (*Schema) MergeProperty 

func (s *Schema) MergeProperty(p Property) error

func (Schema) TypeDecl 

func (s Schema) TypeDecl() string

type SchemaDescriptor 

type SchemaDescriptor struct {
	Fields                   []FieldDescriptor
	HasAdditionalProperties  bool
	AdditionalPropertiesType string
}

This describes a Schema, a type definition.

type SecurityDefinition 

type SecurityDefinition struct {
	ProviderName string
	Scopes       []string
}

func DescribeSecurityDefinition 

func DescribeSecurityDefinition(securityRequirements openapi3.SecurityRequirements) []SecurityDefinition

type TypeDefinition 

type TypeDefinition struct {
	TypeName     string
	JsonName     string
	ResponseName string
	Schema       Schema
}

func GenerateParamsTypes 

func GenerateParamsTypes(op OperationDefinition) []TypeDefinition

This defines the schema for a parameters definition object which encapsulates all the query, header and cookie parameters for an operation.

func GenerateTypeDefsForOperation 

func GenerateTypeDefsForOperation(op OperationDefinition) []TypeDefinition

func GenerateTypesForParameters 

func GenerateTypesForParameters(t *template.Template, params map[string]*openapi3.ParameterRef) ([]TypeDefinition, error)

Generates type definitions for any custom types defined in the components/parameters section of the Swagger spec.

func GenerateTypesForRequestBodies 

func GenerateTypesForRequestBodies(t *template.Template, bodies map[string]*openapi3.RequestBodyRef) ([]TypeDefinition, error)

Generates type definitions for any custom types defined in the components/requestBodies section of the Swagger spec.

func GenerateTypesForResponses 

func GenerateTypesForResponses(t *template.Template, responses openapi3.Responses) ([]TypeDefinition, error)

Generates type definitions for any custom types defined in the components/responses section of the Swagger spec.

func GenerateTypesForSchemas 

func GenerateTypesForSchemas(t *template.Template, schemas map[string]*openapi3.SchemaRef) ([]TypeDefinition, error)

Generates type definitions for any custom types defined in the components/schemas section of the Swagger spec.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.