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 ¶
- Variables
- func DoTidy(w io.Writer, rule TidyRule, s string) string
- func EscapePathElements(path string) string
- func GenFieldsFromProperties(props []Property) []string
- func GenStructFromAllOf(allOf []*openapi3.SchemaRef, path []string) (string, error)
- func GenStructFromSchema(schema Schema) string
- func Generate(spec *openapi3.T, opts Configuration) (string, error)
- func GenerateAdditionalPropertyBoilerplate(t *template.Template, typeDefs []TypeDefinition) (string, error)
- func GenerateBodyDefinitions(operationID string, bodyOrRef *openapi3.RequestBodyRef) ([]RequestBodyDefinition, []TypeDefinition, error)
- func GenerateChiServer(t *template.Template, operations []OperationDefinition) (string, error)
- func GenerateClient(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateClientFactory(services []ClientService, opts Configuration) (string, error)
- func GenerateClientServiceWithResponses(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateClientWithResponses(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateConstants(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateEchoServer(t *template.Template, operations []OperationDefinition) (string, error)
- func GenerateEnums(t *template.Template, types []TypeDefinition) (string, error)
- func GenerateGinServer(t *template.Template, operations []OperationDefinition) (string, error)
- func GenerateGorillaServer(t *template.Template, operations []OperationDefinition) (string, error)
- func GenerateImports(t *template.Template, externalImports []string, packageName string) (string, error)
- func GenerateInlinedSpec(t *template.Template, importMapping importMap, swagger *openapi3.T) (string, error)
- func GenerateServiceClient(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateStrictResponses(t *template.Template, responses []ResponseDefinition) (string, error)
- func GenerateStrictServer(t *template.Template, operations []OperationDefinition, opts Configuration) (string, error)
- func GenerateTemplates(templates []string, t *template.Template, ops interface{}) (string, error)
- func GenerateTypeDefinitions(t *template.Template, swagger *openapi3.T, ops []OperationDefinition, ...) (string, error)
- func GenerateTypes(t *template.Template, types []TypeDefinition) (string, error)
- func GenerateTypesForOperations(t *template.Template, ops []OperationDefinition) (string, error)
- func GenerateUnionBoilerplate(t *template.Template, typeDefs []TypeDefinition) (string, error)
- func GetParametersImports(params map[string]*openapi3.ParameterRef) (map[string]goImport, error)
- func GetRequestBodiesImports(bodies map[string]*openapi3.RequestBodyRef) (map[string]goImport, error)
- func GetResponsesImports(responses map[string]*openapi3.ResponseRef) (map[string]goImport, error)
- func GetSchemaImports(schemas map[string]*openapi3.SchemaRef, excludeSchemas []string) (map[string]goImport, error)
- func GetTypeDefinitionsImports(swagger *openapi3.T, excludeSchemas []string) (map[string]goImport, error)
- func GoSchemaImports(schemas ...*openapi3.SchemaRef) (map[string]goImport, error)
- func IsGoIdentity(str string) bool
- func IsGoKeyword(str string) bool
- func IsGoTypeReference(ref string) bool
- func IsPredeclaredGoIdentifier(str string) bool
- func IsValidGoIdentity(str string) bool
- func IsWholeDocumentReference(ref string) bool
- func LoadTemplates(src embed.FS, t *template.Template) error
- func LowercaseFirstCharacter(str string) string
- func MergeImports(dst, src map[string]goImport)
- func OperationImports(ops []OperationDefinition) (map[string]goImport, error)
- func OperationSchemaImports(s *Schema) (map[string]goImport, error)
- func OrderedParamsFromUri(uri string) []string
- func ParseGoImportExtension(v *openapi3.SchemaRef) (*goImport, error)
- func PathToTypeName(path []string) string
- func PropertiesEqual(a, b Property) bool
- func RefPathToGoType(refPath string) (string, error)
- func ReplacePathParamsWithStr(uri string) string
- func SanitizeCode(goCode string) string
- func SanitizeEnumNames(enumNames []string) map[string]string
- func SanitizeGoIdentity(str string) string
- func SchemaHasAdditionalProperties(schema *openapi3.Schema) bool
- func SchemaNameToTypeName(name string) string
- func SchemaNameToUpperSnake(name string) string
- func SortedContentKeys(dict openapi3.Content) []string
- func SortedHeadersKeys(dict openapi3.Headers) []string
- func SortedOperationsKeys(dict map[string]*openapi3.Operation) []string
- func SortedParameterKeys(dict map[string]*openapi3.ParameterRef) []string
- func SortedPathsKeys(dict openapi3.Paths) []string
- func SortedRequestBodyKeys(dict map[string]*openapi3.RequestBodyRef) []string
- func SortedResponsesKeys(dict openapi3.Responses) []string
- func SortedSchemaKeys(dict map[string]*openapi3.SchemaRef) []string
- func SortedSecurityRequirementKeys(sr openapi3.SecurityRequirement) []string
- func SortedStringKeys(dict map[string]string) []string
- func StringInArray(str string, array []string) bool
- func StringToGoComment(in string) string
- func StringWithTypeNameToGoComment(in, typeName string) string
- func SwaggerUriToChiUri(uri string) string
- func SwaggerUriToEchoUri(uri string) string
- func SwaggerUriToFiberUri(uri string) string
- func SwaggerUriToGinUri(uri string) string
- func SwaggerUriToGorillaUri(uri string) string
- func ToCamelCase(str string) string
- func TypeDefinitionsEquivalent(t1, t2 TypeDefinition) bool
- func UppercaseFirstCharacter(str string) string
- func UppercaseFirstCharacterWithPkgName(str string) string
- type AdditionalImport
- type ClientService
- type CompatibilityOptions
- type Configuration
- type Constants
- type CopyItem
- type CustomDoer
- type Discriminator
- type EnumDefinition
- type ExtendResponseItem
- type FieldDescriptor
- type FileSplit
- type GenerateOptions
- type OperationDefinition
- func (o *OperationDefinition) AllParams() []ParameterDefinition
- func (o *OperationDefinition) GetResponseTypeDefinitions() ([]ResponseTypeDefinition, error)
- func (o *OperationDefinition) HasBody() bool
- func (o OperationDefinition) HasMaskedRequestContentTypes() bool
- func (o *OperationDefinition) Params() []ParameterDefinition
- func (o *OperationDefinition) RequiresParamObject() bool
- func (o *OperationDefinition) SummaryAsComment() string
- type OutputOptions
- type ParameterDefinition
- func (pd *ParameterDefinition) Explode() bool
- func (pd ParameterDefinition) GoName() string
- func (pd ParameterDefinition) GoVariableName() string
- func (pd ParameterDefinition) IndirectOptional() bool
- func (pd *ParameterDefinition) IsJson() bool
- func (pd *ParameterDefinition) IsPassThrough() bool
- func (pd *ParameterDefinition) IsStyled() bool
- func (pd *ParameterDefinition) JsonTag() string
- func (pd *ParameterDefinition) Style() string
- func (pd ParameterDefinition) TypeDef() string
- type ParameterDefinitions
- type Property
- type RefWrapper
- type RequestBodyDefinition
- func (r RequestBodyDefinition) CustomType() bool
- func (r RequestBodyDefinition) IsFixedContentType() bool
- func (r RequestBodyDefinition) IsSupported() bool
- func (r RequestBodyDefinition) IsSupportedByClient() bool
- func (r RequestBodyDefinition) Suffix() string
- func (r RequestBodyDefinition) TypeDef(opID string) *TypeDefinition
- type RequestBodyEncoding
- type ResponseContentDefinition
- type ResponseDefinition
- type ResponseHeaderDefinition
- type ResponseTypeDefinition
- type Schema
- type SchemaDescriptor
- type SecurityDefinition
- type Tidy
- type TidyRule
- type TypeDefinition
- func GenerateParamsTypes(op OperationDefinition) []TypeDefinition
- func GenerateTypeDefsForOperation(op OperationDefinition) []TypeDefinition
- func GenerateTypesForParameters(t *template.Template, params map[string]*openapi3.ParameterRef) ([]TypeDefinition, error)
- func GenerateTypesForRequestBodies(t *template.Template, bodies map[string]*openapi3.RequestBodyRef) ([]TypeDefinition, error)
- func GenerateTypesForResponses(t *template.Template, responses openapi3.Responses) ([]TypeDefinition, error)
- func GenerateTypesForSchemas(t *template.Template, schemas map[string]*openapi3.SchemaRef, ...) ([]TypeDefinition, error)
- type UnionElement
Constants ¶
This section is empty.
Variables ¶
var TemplateFunctions = template.FuncMap{ "genParamArgs": genParamArgs, "genParamTypes": genParamTypes, "genParamNames": genParamNames, "genParamFmtString": ReplacePathParamsWithStr, "swaggerUriToEchoUri": SwaggerUriToEchoUri, "swaggerUriToChiUri": SwaggerUriToChiUri, "swaggerUriToGinUri": SwaggerUriToGinUri, "swaggerUriToGorillaUri": SwaggerUriToGorillaUri, "lcFirst": LowercaseFirstCharacter, "ucFirst": UppercaseFirstCharacter, "ucFirstWithPkgName": UppercaseFirstCharacterWithPkgName, "camelCase": ToCamelCase, "genResponsePayload": genResponsePayload, "genResponseTypeName": genResponseTypeName, "genResponseUnmarshal": genResponseUnmarshal, "getResponseTypeDefinitions": getResponseTypeDefinitions, "toStringArray": toStringArray, "lower": strings.ToLower, "upper": strings.ToUpper, "title": titleCaser.String, "stripNewLines": stripNewLines, "sanitizeGoIdentity": SanitizeGoIdentity, "toGoComment": StringWithTypeNameToGoComment, "has": has, "iif": iif, "toSnakeCase": toSnakeCase, }
TemplateFunctions is passed to the template engine, and we can call each function here by keyName from the template code.
Functions ¶
func EscapePathElements ¶
EscapePathElements breaks apart a path, and looks at each element. If it's not a path parameter, eg, {param}, it will URL-escape the element.
func GenFieldsFromProperties ¶
GenFieldsFromProperties produce corresponding field names with JSON annotations, given a list of schema descriptors
func GenStructFromAllOf ¶
GenStructFromAllOf 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 Generate ¶
func Generate(spec *openapi3.T, opts Configuration) (string, error)
Generate 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)
GenerateAdditionalPropertyBoilerplate generates 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)
GenerateBodyDefinitions 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)
GenerateClient uses the template engine to generate the function which registers our wrappers as Echo path handlers.
func GenerateClientFactory ¶
func GenerateClientFactory(services []ClientService, opts Configuration) (string, error)
func GenerateClientServiceWithResponses ¶
func GenerateClientServiceWithResponses(t *template.Template, ops []OperationDefinition) (string, error)
GenerateClientServiceWithResponses generates a client service which extends the basic client which does response unmarshalling.
func GenerateClientWithResponses ¶
func GenerateClientWithResponses(t *template.Template, ops []OperationDefinition) (string, error)
GenerateClientWithResponses generates a client which extends the basic client which does response unmarshalling.
func GenerateConstants ¶
func GenerateConstants(t *template.Template, ops []OperationDefinition) (string, error)
GenerateConstants generates operation ids, context keys, paths, etc. to be exported as constants
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 GenerateEnums ¶
func GenerateEnums(t *template.Template, types []TypeDefinition) (string, error)
func GenerateGinServer ¶
func GenerateGinServer(t *template.Template, operations []OperationDefinition) (string, error)
GenerateGinServer generates all the go code for the ServerInterface as well as all the wrapper functions around our handlers.
func GenerateGorillaServer ¶
func GenerateGorillaServer(t *template.Template, operations []OperationDefinition) (string, error)
GenerateGorillaServer 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, externalImports []string, packageName string) (string, error)
GenerateImports generates our import statements and package definition.
func GenerateInlinedSpec ¶
func GenerateInlinedSpec(t *template.Template, importMapping importMap, swagger *openapi3.T) (string, error)
GenerateInlinedSpec generates a gzipped, base64 encoded JSON representation of the swagger definition, which we embed inside the generated code.
func GenerateServiceClient ¶
func GenerateServiceClient(t *template.Template, ops []OperationDefinition) (string, error)
GenerateServiceClient generates client of factory service
func GenerateStrictResponses ¶
func GenerateStrictResponses(t *template.Template, responses []ResponseDefinition) (string, error)
func GenerateStrictServer ¶
func GenerateStrictServer(t *template.Template, operations []OperationDefinition, opts Configuration) (string, error)
func GenerateTemplates ¶
GenerateTemplates used to generate templates
func GenerateTypeDefinitions ¶
func GenerateTypes ¶
func GenerateTypes(t *template.Template, types []TypeDefinition) (string, error)
GenerateTypes passes a bunch of types to the template engine, and buffers its output into a string.
func GenerateTypesForOperations ¶
func GenerateTypesForOperations(t *template.Template, ops []OperationDefinition) (string, error)
GenerateTypesForOperations generates code for all types produced within operations
func GenerateUnionBoilerplate ¶
func GenerateUnionBoilerplate(t *template.Template, typeDefs []TypeDefinition) (string, error)
func GetParametersImports ¶
func GetParametersImports(params map[string]*openapi3.ParameterRef) (map[string]goImport, error)
func GetRequestBodiesImports ¶
func GetRequestBodiesImports(bodies map[string]*openapi3.RequestBodyRef) (map[string]goImport, error)
func GetResponsesImports ¶
func GetResponsesImports(responses map[string]*openapi3.ResponseRef) (map[string]goImport, error)
func GetSchemaImports ¶
func GoSchemaImports ¶
func IsGoIdentity ¶
IsGoIdentity checks if the given string can be used as an identity in the generated code like a type name or constant name.
func IsGoKeyword ¶
IsGoKeyword returns whether the given string is a go keyword
func IsGoTypeReference ¶
IsGoTypeReference takes a $ref value and checks if it has link to go type. #/components/schemas/Foo -> true ./local/file.yml#/components/parameters/Bar -> true ./local/file.yml -> false IsGoTypeReference can be used to check whether RefPathToGoType($ref) is possible.
func IsPredeclaredGoIdentifier ¶
IsPredeclaredGoIdentifier returns whether the given string is a predefined go indentifier.
func IsValidGoIdentity ¶
IsValidGoIdentity checks if the given string can be used as a name of variable, constant, or type.
func IsWholeDocumentReference ¶
IsWholeDocumentReference takes a $ref value and checks if it is whole document reference. #/components/schemas/Foo -> false ./local/file.yml#/components/parameters/Bar -> false ./local/file.yml -> true http://deepmap.com/schemas/document.json -> true http://deepmap.com/schemas/document.json#/Foo -> false
func LoadTemplates ¶
LoadTemplates loads all of our template files into a text/template. The path of template is relative to the templates directory.
func LowercaseFirstCharacter ¶
LowercaseFirstCharacter Lowercases 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.
func MergeImports ¶
func MergeImports(dst, src map[string]goImport)
func OperationImports ¶
func OperationImports(ops []OperationDefinition) (map[string]goImport, error)
func OperationSchemaImports ¶
func OrderedParamsFromUri ¶
OrderedParamsFromUri returns the argument names, in order, in a given URI string, so for /path/{param1}/{.param2*}/{?param3}, it would return param1, param2, param3
func ParseGoImportExtension ¶
func PathToTypeName ¶
PathToTypeName converts a path, like Object/field1/nestedField into a go type name.
func PropertiesEqual ¶
func RefPathToGoType ¶
RefPathToGoType 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 supported if they present in --import-mapping URL components (http://deepmap.com/schemas/document.json#/Foo) are supported if they present in --import-mapping Remote and URL also support standard local paths even though the spec doesn't mention them.
func ReplacePathParamsWithStr ¶
ReplacePathParamsWithStr replaces path parameters of the form {param} with %s
func SanitizeCode ¶
SanitizeCode runs sanitizers across the generated Go code to ensure the generated code will be able to compile.
func SanitizeEnumNames ¶
SanitizeEnumNames fixes illegal chars in the enum names and removes duplicates
func SanitizeGoIdentity ¶
SanitizeGoIdentity deletes and replaces the illegal runes in the given string to use the string as a valid identity.
func SchemaHasAdditionalProperties ¶
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 ¶
SchemaNameToTypeName 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 SchemaNameToUpperSnake ¶
SchemaNameToTypeNameNoCamel converts a Schema name to a valid Go type name. It doesn't converts to camel case
func SortedContentKeys ¶
SortedContentKeys returns Content dictionary keys in sorted order
func SortedHeadersKeys ¶
func SortedOperationsKeys ¶
SortedOperationsKeys returns Operation dictionary keys in sorted order
func SortedParameterKeys ¶
func SortedParameterKeys(dict map[string]*openapi3.ParameterRef) []string
SortedParameterKeys returns sorted keys for a ParameterRef dict
func SortedPathsKeys ¶
SortedPathsKeys 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 ¶
SortedResponsesKeys returns Responses dictionary keys in sorted order
func SortedSchemaKeys ¶
SortedSchemaKeys returns the keys of the given SchemaRef dictionary in sorted order, since Golang scrambles dictionary keys
func SortedSecurityRequirementKeys ¶
func SortedSecurityRequirementKeys(sr openapi3.SecurityRequirement) []string
func SortedStringKeys ¶
SortedStringKeys returns string map keys in sorted order
func StringInArray ¶
StringInArray checks whether the specified string is present in an array of strings
func StringToGoComment ¶
StringToGoComment renders a possible multi-line string as a valid Go-Comment. Each line is prefixed as a comment.
func StringWithTypeNameToGoComment ¶
StringWithTypeNameToGoComment renders a possible multi-line string as a valid Go-Comment, including the name of the type being referenced. Each line is prefixed as a comment.
func SwaggerUriToChiUri ¶
SwaggerUriToChiUri converts a swagger style path URI with parameters to a Chi compatible path URI. We need to replace all Swagger parameters with "{param}". Valid input parameters are:
{param} {param*} {.param} {.param*} {;param} {;param*} {?param} {?param*}
func SwaggerUriToEchoUri ¶
SwaggerUriToEchoUri converts a OpenAPI style path URI with parameters to an Echo compatible path URI. We need to replace all of OpenAPI parameters with ":param". Valid input parameters are:
{param} {param*} {.param} {.param*} {;param} {;param*} {?param} {?param*}
func SwaggerUriToFiberUri ¶
SwaggerUriToFiberUri converts a OpenAPI style path URI with parameters to a Fiber compatible path URI. We need to replace all of OpenAPI parameters with ":param". Valid input parameters are:
{param} {param*} {.param} {.param*} {;param} {;param*} {?param} {?param*}
func SwaggerUriToGinUri ¶
SwaggerUriToGinUri converts a swagger style path URI with parameters to a Gin compatible path URI. We need to replace all Swagger parameters with ":param". Valid input parameters are:
{param} {param*} {.param} {.param*} {;param} {;param*} {?param} {?param*}
func SwaggerUriToGorillaUri ¶
SwaggerUriToGorillaUri converts a swagger style path URI with parameters to a Gorilla compatible path URI. We need to replace all Swagger parameters with ":param". Valid input parameters are:
{param} {param*} {.param} {.param*} {;param} {;param*} {?param} {?param*}
func ToCamelCase ¶
ToCamelCase 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 TypeDefinitionsEquivalent ¶
func TypeDefinitionsEquivalent(t1, t2 TypeDefinition) bool
TypeDefinitionsEquivalent checks for equality between two type definitions, but not every field is considered. We only want to know if they are fundamentally the same type.
func UppercaseFirstCharacter ¶
UppercaseFirstCharacter Uppercases 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.
func UppercaseFirstCharacterWithPkgName ¶
Uppercase the first character in a identifier with pkg name. This assumes UTF-8, so we have to be careful with unicode, don't treat it as a byte array.
Types ¶
type AdditionalImport ¶
type ClientService ¶
type CompatibilityOptions ¶
type CompatibilityOptions struct { // In the past, we merged schemas for `allOf` by inlining each schema // within the schema list. This approach, though, is incorrect because // `allOf` merges at the schema definition level, not at the resulting model // level. So, new behavior merges OpenAPI specs but generates different code // than we have in the past. Set OldMergeSchemas to true for the old behavior. // Please see https://github.com/do87/stackit-client-generator/issues/531 OldMergeSchemas bool `yaml:"old-merge-schemas,omitempty"` // Enum values can generate conflicting typenames, so we've updated the // code for enum generation to avoid these conflicts, but it will result // in some enum types being renamed in existing code. Set OldEnumConflicts to true // to revert to old behavior. Please see: // Please see https://github.com/do87/stackit-client-generator/issues/549 OldEnumConflicts bool `yaml:"old-enum-conflicts,omitempty"` // It was a mistake to generate a go type definition for every $ref in // the OpenAPI schema. New behavior uses type aliases where possible, but // this can generate code which breaks existing builds. Set OldAliasing to true // for old behavior. // Please see https://github.com/do87/stackit-client-generator/issues/549 OldAliasing bool `yaml:"old-aliasing,omitempty"` // When an object contains no members, and only an additionalProperties specification, // it is flattened to a map. Set DisableFlattenAdditionalProperties bool `yaml:"disable-flatten-additional-properties,omitempty"` // When an object property is both required and readOnly the go model is generated // as a pointer. Set DisableRequiredReadOnlyAsPointer to true to mark them as non pointer. // Please see https://github.com/do87/stackit-client-generator/issues/604 DisableRequiredReadOnlyAsPointer bool `yaml:"disable-required-readonly-as-pointer,omitempty"` // When set to true, always prefix enum values with their type name instead of only // when typenames would be conflicting. AlwaysPrefixEnumValues bool `yaml:"always-prefix-enum-values,omitempty"` // Our generated code for Chi has historically inverted the order in which Chi middleware is // applied such that the last invoked middleware ends up executing first in the Chi chain // This resolves the behavior such that middlewares are chained in the order they are invoked. // Please see https://github.com/do87/stackit-client-generator/issues/786 ApplyChiMiddlewareFirstToLast bool `yaml:"apply-chi-middleware-first-to-last,omitempty"` }
CompatibilityOptions specifies backward compatibility settings for the code generator.
type Configuration ¶
type Configuration struct { PackageName string `yaml:"package"` // PackageName to generate Generate GenerateOptions `yaml:"generate,omitempty"` Compatibility CompatibilityOptions `yaml:"compatibility,omitempty"` OutputOptions OutputOptions `yaml:"output-options,omitempty"` ImportMapping map[string]string `yaml:"import-mapping,omitempty"` // ImportMapping specifies the golang package path for each external reference AdditionalImports []AdditionalImport `yaml:"additional-imports,omitempty"` Tidy Tidy `yaml:"tidy,omitempty"` }
Configuration defines code generation customizations
func (Configuration) UpdateDefaults ¶
func (o Configuration) UpdateDefaults() Configuration
UpdateDefaults sets reasonable default values for unset fields in Configuration
func (Configuration) Validate ¶
func (o Configuration) Validate() error
Validate checks whether Configuration represent a valid configuration
type Constants ¶
type Constants struct { // SecuritySchemeProviderNames holds all provider names for security schemes. SecuritySchemeProviderNames []string // EnumDefinitions holds type and value information for all enums EnumDefinitions []EnumDefinition }
type CustomDoer ¶
type Discriminator ¶
type Discriminator struct { // maps discriminator value to go type Mapping map[string]string // JSON property name that holds the discriminator Property string }
func (*Discriminator) JSONTag ¶
func (d *Discriminator) JSONTag() string
func (*Discriminator) PropertyName ¶
func (d *Discriminator) PropertyName() string
type EnumDefinition ¶
type EnumDefinition struct { // Schema is the scheme of a type which has a list of enum values, eg, the // "container" of the enum. Schema Schema // TypeName is the name of the enum's type, usually aliased from something. TypeName string // ValueWrapper wraps the value. It's used to conditionally apply quotes // around strings. ValueWrapper string // PrefixTypeName determines if the enum value is prefixed with its TypeName. // This is set to true when this enum conflicts with another in terms of // TypeNames or when explicitly requested via the // `compatibility.always-prefix-enum-values` option. PrefixTypeName bool }
EnumDefinition holds type information for enum
func (*EnumDefinition) GetValues ¶
func (e *EnumDefinition) GetValues() map[string]string
GetValues generates enum names in a way to minimize global conflicts
type ExtendResponseItem ¶
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 GenerateOptions ¶
type GenerateOptions struct { ChiServer bool `yaml:"chi-server,omitempty"` // ChiServer specifies whether to generate chi server boilerplate EchoServer bool `yaml:"echo-server,omitempty"` // EchoServer specifies whether to generate echo server boilerplate GinServer bool `yaml:"gin-server,omitempty"` // GinServer specifies whether to generate gin server boilerplate GorillaServer bool `yaml:"gorilla-server,omitempty"` // GorillaServer specifies whether to generate Gorilla server boilerplate Strict bool `yaml:"strict-server,omitempty"` // Strict specifies whether to generate strict server wrapper Client bool `yaml:"client,omitempty"` // Client specifies whether to generate client boilerplate Models bool `yaml:"models,omitempty"` // Models specifies whether to generate type definitions EmbeddedSpec bool `yaml:"embedded-spec,omitempty"` // Whether to embed the swagger spec in the generated code }
GenerateOptions specifies which supported output formats to generate.
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. Responses []ResponseDefinition // The list of responses that can be accepted by 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 }
OperationDefinition describes an Operation
func OperationDefinitions ¶
func OperationDefinitions(swagger *openapi3.T) ([]OperationDefinition, error)
OperationDefinitions returns all operations for a swagger definition.
func (*OperationDefinition) AllParams ¶
func (o *OperationDefinition) AllParams() []ParameterDefinition
AllParams returns all parameters
func (*OperationDefinition) GetResponseTypeDefinitions ¶
func (o *OperationDefinition) GetResponseTypeDefinitions() ([]ResponseTypeDefinition, error)
GetResponseTypeDefinitions 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
HasBody 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 we generate types for them.
func (OperationDefinition) HasMaskedRequestContentTypes ¶
func (o OperationDefinition) HasMaskedRequestContentTypes() bool
func (*OperationDefinition) Params ¶
func (o *OperationDefinition) Params() []ParameterDefinition
Params 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
SummaryAsComment returns the Operations summary as a multi line comment
type OutputOptions ¶
type OutputOptions struct { SkipFmt bool `yaml:"skip-fmt,omitempty"` // Whether to skip go imports on the generated code SkipPrune bool `yaml:"skip-prune,omitempty"` // Whether to skip pruning unused components on the generated code IncludeTags []string `yaml:"include-tags,omitempty"` // Only include operations that have one of these tags. Ignored when empty. ExcludeTags []string `yaml:"exclude-tags,omitempty"` // Exclude operations that have one of these tags. Ignored when empty. UserTemplates map[string]string `yaml:"user-templates,omitempty"` // Override built-in templates from user-provided files ExcludeSchemas []string `yaml:"exclude-schemas,omitempty"` // Exclude from generation schemas with given names. Ignored when empty. ResponseTypeSuffix string `yaml:"response-type-suffix,omitempty"` // The suffix used for responses types ClientTypeName string `yaml:"client-type-name,omitempty"` // Override the default generated client type with the value SplitByTags FileSplit `yaml:"split-by-tags,omitempty"` // FileSplit splits to separate files/dirs according to tags ExtendResponse []ExtendResponseItem `yaml:"extend-response,omitempty"` // FileSplit splits to separate files/dirs according to tags CustomDoer CustomDoer `yaml:"custom-doer,omitempty"` // FileSplit splits to separate files/dirs according to tags Copy []CopyItem `yaml:"copy,omitempty"` // Files to copy }
OutputOptions are used to modify the output code in some way.
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)
DescribeParameters 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
FilterParameterDefinitionByType returns the subset of the specified parameters which are of the specified type.
func SortParamsByPath ¶
func SortParamsByPath(path string, in []ParameterDefinition) ([]ParameterDefinition, error)
SortParamsByPath 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
JsonTag generates 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
TypeDef 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 Nullable bool ReadOnly bool WriteOnly bool NeedsFormTag bool ExtensionProps *openapi3.ExtensionProps }
func (Property) GoFieldName ¶
type RefWrapper ¶
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 // Contains encoding options for formdata Encoding map[string]RequestBodyEncoding }
RequestBodyDefinition describes a request body
func (RequestBodyDefinition) CustomType ¶
func (r RequestBodyDefinition) CustomType() bool
CustomType 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) IsFixedContentType ¶
func (r RequestBodyDefinition) IsFixedContentType() bool
IsFixedContentType returns true if content type has fixed content type, i.e. contains no "*" symbol
func (RequestBodyDefinition) IsSupported ¶
func (r RequestBodyDefinition) IsSupported() bool
IsSupported returns true if we support this content type for server. Otherwise io.Reader will be generated
func (RequestBodyDefinition) IsSupportedByClient ¶
func (r RequestBodyDefinition) IsSupportedByClient() bool
IsSupportedByClient returns true if we support this content type for client. Otherwise only generic method will ge generated
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(opID string) *TypeDefinition
TypeDef returns the Go type definition for a request body
type RequestBodyEncoding ¶
type ResponseContentDefinition ¶
type ResponseContentDefinition struct { // This is the schema describing this content Schema Schema // This is the content type corresponding to the body, eg, application/json ContentType string // When we generate type names, we need a Tag for it, such as JSON, in // which case we will produce "Response200JSONContent". NameTag string }
func (ResponseContentDefinition) HasFixedContentType ¶
func (r ResponseContentDefinition) HasFixedContentType() bool
HasFixedContentType returns true if content type has fixed content type, i.e. contains no "*" symbol
func (ResponseContentDefinition) IsSupported ¶
func (r ResponseContentDefinition) IsSupported() bool
func (ResponseContentDefinition) NameTagOrContentType ¶
func (r ResponseContentDefinition) NameTagOrContentType() string
func (ResponseContentDefinition) TypeDef ¶
func (r ResponseContentDefinition) TypeDef(opID string, statusCode int) *TypeDefinition
TypeDef returns the Go type definition for a request body
type ResponseDefinition ¶
type ResponseDefinition struct { StatusCode string Description string Contents []ResponseContentDefinition Headers []ResponseHeaderDefinition Ref string }
func GenerateResponseDefinitions ¶
func GenerateResponseDefinitions(operationID string, responses openapi3.Responses) ([]ResponseDefinition, error)
func (ResponseDefinition) GoName ¶
func (r ResponseDefinition) GoName() string
func (ResponseDefinition) HasFixedStatusCode ¶
func (r ResponseDefinition) HasFixedStatusCode() bool
func (ResponseDefinition) IsRef ¶
func (r ResponseDefinition) IsRef() bool
type ResponseTypeDefinition ¶
type ResponseTypeDefinition struct { TypeDefinition // The content type name where this is used, eg, application/json ContentTypeName string // The type name of a response model. ResponseName string }
ResponseTypeDefinition is an extension of TypeDefinition, specifically for response unmarshalling in ClientWithResponses.
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 ArrayType *Schema // The schema of array element EnumValues map[string]string // Enum values 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 Description string // The description of the element UnionElements []UnionElement // Possible elements of oneOf/anyOf union Discriminator *Discriminator // Describes which value is stored in a union // If this is set, the schema will declare a type via alias, eg, // `type Foo = bool`. If this is not set, we will define this type via // type definition `type Foo bool` DefineViaAlias bool // The original OpenAPIv3 Schema. OAPISchema *openapi3.Schema }
Schema describes an OpenAPI schema, with lots of helper fields to use in the templating engine.
func GenerateGoSchema ¶
func MergeSchemas ¶
MergeSchemas merges all the fields in the schemas supplied into one giant schema. The idea is that we merge all fields together into one schema.
func (*Schema) AddProperty ¶
AddProperty adds a new property to the current Schema, and returns an error if it collides. Two identical fields will not collide, but two properties by the same name, but different definition, will collide. It's safe to merge the fields of two schemas with overalapping properties if those properties are identical.
func (Schema) GetAdditionalTypeDefs ¶
func (s Schema) GetAdditionalTypeDefs() []TypeDefinition
type SchemaDescriptor ¶
type SchemaDescriptor struct { Fields []FieldDescriptor HasAdditionalProperties bool AdditionalPropertiesType string }
SchemaDescriptor describes a Schema, a type definition.
type SecurityDefinition ¶
func DescribeSecurityDefinition ¶
func DescribeSecurityDefinition(securityRequirements openapi3.SecurityRequirements) []SecurityDefinition
type TidyRule ¶
type TidyRule struct { Replace string `yaml:"replace,omitempty"` With string `yaml:"with,omitempty"` Prefix bool `yaml:"prefix,omitempty"` Suffix bool `yaml:"suffix,omitempty"` All bool `yaml:"all,omitempty"` Match bool `yaml:"match,omitempty"` }
Tidy is a list of rules for replacing strings in the openAPI file
type TypeDefinition ¶
type TypeDefinition struct { // The name of the type, eg, type <...> Person TypeName string // The name of the corresponding JSON description, as it will sometimes // differ due to invalid characters. JsonName string // This is the Schema wrapper is used to populate the type description Schema Schema }
TypeDefinition describes a Go type definition in generated code.
Let's use this example schema: components:
schemas: Person: type: object properties: name: type: string
func GenerateParamsTypes ¶
func GenerateParamsTypes(op OperationDefinition) []TypeDefinition
GenerateParamsTypes 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)
GenerateTypesForParameters 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)
GenerateTypesForRequestBodies 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)
GenerateTypesForResponses 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, excludeSchemas []string) ([]TypeDefinition, error)
GenerateTypesForSchemas generates type definitions for any custom types defined in the components/schemas section of the Swagger spec.
func (*TypeDefinition) IsAlias ¶
func (t *TypeDefinition) IsAlias() bool
type UnionElement ¶
type UnionElement string
UnionElement describe union element, based on prefix externalRef\d+ and real ref name from external schema.
func (UnionElement) Method ¶
func (u UnionElement) Method() string
Method generate union method name for template functions `As/From/Merge`.
func (UnionElement) String ¶
func (u UnionElement) String() string
String returns externalRef\d+ and real ref name from external schema, like externalRef0.SomeType.