func FixEmptyDesc(rs *spec.Response)
FixEmptyDesc adds "(empty)" as the description to the given Response object if it doesn't already have one and isn't a ref. No-op on nil input.
func FixEmptyDescs(rs *spec.Responses)
FixEmptyDescs adds "(empty)" as the description for any Response in the given Responses object that doesn't already have one.
func FixEmptyResponseDescriptions(s *spec.Swagger)
FixEmptyResponseDescriptions replaces empty ("") response descriptions in the input with "(empty)" to ensure that the resulting Swagger is stays valid. The problem appears to arise from reading in valid specs that have a explicit response description of "" (valid, response.description is required), but due to zero values being omitted upon re-serializing (omitempty) we lose them unless we stick some chars in there.
func Flatten(opts FlattenOpts) error
Flatten an analyzed spec and produce a self-contained spec bundle.
There is a minimal and a full flattening mode.
Minimally flattening a spec means:
A minimally flattened spec thus guarantees the following properties:
NOTE: arbitrary JSON pointers (other than $refs to top level definitions) are rewritten as definitions if they represent a complex schema or express commonality in the spec. Otherwise, they are simply expanded. Self-referencing JSON pointers cannot resolve to a type and trigger an error.
Minimal flattening is necessary and sufficient for codegen rendering using go-swagger.
Fully flattening a spec means:
By complex, we mean every JSON object with some properties. Arrays, when they do not define a tuple, or empty objects with or without additionalProperties, are not considered complex and remain inline.
NOTE: rewritten schemas get a vendor extension x-go-gen-location so we know from which part of the spec definitions have been created.
Available flattening options:
NOTE: expansion removes all $ref save circular $ref, which remain in place
TODO: additional options
func GenLocation(parts sortref.SplitKey) string
GenLocation indicates from which section of the specification (models or operations) a definition has been created.
This is reflected in the output spec with a "x-go-gen-location" extension. At the moment, this is provided for information only.
func Mixin(primary *spec.Swagger, mixins ...*spec.Swagger) []string
Mixin modifies the primary swagger spec by adding the paths and definitions from the mixin specs. Top level parameters and responses from the mixins are also carried over. Operation id collisions are avoided by appending "Mixin<N>" but only if needed.
The following parts of primary are subject to merge, filling empty details
Consider calling FixEmptyResponseDescriptions() on the modified primary if you read them from storage and they are valid to start with.
Entries in "paths", "definitions", "parameters" and "responses" are added to the primary in the order of the given mixins. If the entry already exists in primary it is skipped with a warning message.
The count of skipped entries (from collisions) is returned so any deviation from the number expected can flag a warning in your build scripts. Carefully review the collisions before accepting them; consider renaming things if possible.
No key normalization takes place (paths, type defs, etc). Ensure they are canonical if your downstream tools do key normalization of any form.
Merging schemes (http, https), and consumers/producers do not account for collisions.
AnalyzedSchema indicates what the schema represents
type AnalyzedSchema struct {
IsKnownType bool
IsSimpleSchema bool
IsArray bool
IsSimpleArray bool
IsMap bool
IsSimpleMap bool
IsExtendedObject bool
IsTuple bool
IsTupleWithExtra bool
IsBaseType bool
IsEnum bool
// contains filtered or unexported fields
}
func Schema(opts SchemaOpts) (*AnalyzedSchema, error)
Schema analysis, will classify the schema according to known patterns.
ErrorOnParamFunc is a callback function to be invoked whenever an error is encountered while resolving references on parameters.
This function takes as input the spec.Parameter which triggered the error and the error itself.
If the callback function returns false, the calling function should bail.
If it returns true, the calling function should continue evaluating parameters. A nil ErrorOnParamFunc must be evaluated as equivalent to panic().
type ErrorOnParamFunc func(spec.Parameter, error) bool
FlattenOpts configuration for flattening a swagger specification.
The BasePath parameter is used to locate remote relative $ref found in the specification. This path is a file: it points to the location of the root document and may be either a local file path or a URL.
If none specified, relative references (e.g. "$ref": "folder/schema.yaml#/definitions/...") found in the spec are searched from the current working directory.
type FlattenOpts struct {
Spec *Spec // The analyzed spec to work with
BasePath string // The location of the root document for this spec to resolve relative $ref
// Flattening options
Expand bool // When true, skip flattening the spec and expand it instead (if Minimal is false)
Minimal bool // When true, do not decompose complex structures such as allOf
Verbose bool // enable some reporting on possible name conflicts detected
RemoveUnused bool // When true, remove unused parameters, responses and definitions after expansion/flattening
ContinueOnError bool // Continue when spec expansion issues are found
KeepNames bool // Do not attempt to jsonify names from references when flattening
// contains filtered or unexported fields
}
func (f *FlattenOpts) ExpandOpts(skipSchemas bool) *spec.ExpandOptions
ExpandOpts creates a spec.ExpandOptions to configure expanding a specification document.
func (f *FlattenOpts) Swagger() *spec.Swagger
Swagger gets the swagger specification for this flatten operation
InlineSchemaNamer finds a new name for an inlined type
type InlineSchemaNamer struct {
Spec *spec.Swagger
Operations map[string]operations.OpRef
// contains filtered or unexported fields
}
func (isn *InlineSchemaNamer) Name(key string, schema *spec.Schema, aschema *AnalyzedSchema) error
Name yields a new name for the inline schema
SchemaOpts configures the schema analyzer
type SchemaOpts struct {
Schema *spec.Schema
Root interface{}
BasePath string
// contains filtered or unexported fields
}
SchemaRef is a reference to a schema
type SchemaRef struct {
Name string
Ref spec.Ref
Schema *spec.Schema
TopLevel bool
}
SecurityRequirement is a representation of a security requirement for an operation
type SecurityRequirement struct {
Name string
Scopes []string
}
Spec is an analyzed specification object. It takes a swagger spec object and turns it into a registry with a bunch of utility methods to act on the information in the spec.
type Spec struct {
// contains filtered or unexported fields
}
func New(doc *spec.Swagger) *Spec
New takes a swagger spec object and returns an analyzed spec document. The analyzed document contains a number of indices that make it easier to reason about semantics of a swagger specification for use in code generation or validation etc.
func (s *Spec) AllDefinitionReferences() (result []string)
AllDefinitionReferences returns json refs for all the discovered schemas
func (s *Spec) AllDefinitions() (result []SchemaRef)
AllDefinitions returns schema references for all the definitions that were discovered
func (s *Spec) AllEnums() map[string][]interface{}
AllEnums returns all the enums found in the spec the map is cloned to avoid accidental changes
func (s *Spec) AllItemsReferences() (result []string)
AllItemsReferences returns the references for all the items in simple schemas (parameters or headers).
NOTE: since Swagger 2.0 forbids $ref in simple params, this should always yield an empty slice for a valid Swagger 2.0 spec.
func (s *Spec) AllParameterReferences() (result []string)
AllParameterReferences returns json refs for all the discovered parameters
func (s *Spec) AllPathItemReferences() (result []string)
AllPathItemReferences returns the references for all the items
func (s *Spec) AllPaths() map[string]spec.PathItem
AllPaths returns all the paths in the swagger spec
func (s *Spec) AllPatterns() map[string]string
AllPatterns returns all the patterns found in the spec the map is cloned to avoid accidental changes
func (s *Spec) AllReferences() (result []string)
AllReferences returns all the references found in the document, with possible duplicates
func (s *Spec) AllRefs() (result []spec.Ref)
AllRefs returns all the unique references found in the document
func (s *Spec) AllResponseReferences() (result []string)
AllResponseReferences returns json refs for all the discovered responses
func (s *Spec) ConsumesFor(operation *spec.Operation) []string
ConsumesFor gets the mediatypes for the operation
func (s *Spec) HeaderEnums() map[string][]interface{}
HeaderEnums returns all the enums found in response headers the map is cloned to avoid accidental changes
func (s *Spec) HeaderPatterns() map[string]string
HeaderPatterns returns all the patterns found in response headers the map is cloned to avoid accidental changes
func (s *Spec) ItemsEnums() map[string][]interface{}
ItemsEnums returns all the enums found in simple array items the map is cloned to avoid accidental changes
func (s *Spec) ItemsPatterns() map[string]string
ItemsPatterns returns all the patterns found in simple array items the map is cloned to avoid accidental changes
func (s *Spec) OperationFor(method, path string) (*spec.Operation, bool)
OperationFor the given method and path
func (s *Spec) OperationForName(operationID string) (string, string, *spec.Operation, bool)
OperationForName gets the operation for the given id
func (s *Spec) OperationIDs() []string
OperationIDs gets all the operation ids based on method an dpath
func (s *Spec) OperationMethodPaths() []string
OperationMethodPaths gets all the operation ids based on method an dpath
func (s *Spec) Operations() map[string]map[string]*spec.Operation
Operations gathers all the operations specified in the spec document
func (s *Spec) ParameterEnums() map[string][]interface{}
ParameterEnums returns all the enums found in parameters the map is cloned to avoid accidental changes
func (s *Spec) ParameterPatterns() map[string]string
ParameterPatterns returns all the patterns found in parameters the map is cloned to avoid accidental changes
func (s *Spec) ParametersFor(operationID string) []spec.Parameter
ParametersFor the specified operation id.
Assumes parameters properly resolve references if any and that such references actually resolve to a parameter object. Otherwise, panics.
func (s *Spec) ParamsFor(method, path string) map[string]spec.Parameter
ParamsFor the specified method and path. Aggregates them with the defaults etc, so it's all the params that apply for the method and path.
Assumes parameters properly resolve references if any and that such references actually resolve to a parameter object. Otherwise, panics.
func (s *Spec) ProducesFor(operation *spec.Operation) []string
ProducesFor gets the mediatypes for the operation
func (s *Spec) RequiredConsumes() []string
RequiredConsumes gets all the distinct consumes that are specified in the specification document
func (s *Spec) RequiredProduces() []string
RequiredProduces gets all the distinct produces that are specified in the specification document
func (s *Spec) RequiredSecuritySchemes() []string
RequiredSecuritySchemes gets all the distinct security schemes that are specified in the swagger spec
func (s *Spec) SafeParametersFor(operationID string, callmeOnError ErrorOnParamFunc) []spec.Parameter
SafeParametersFor the specified operation id.
Does not assume parameters properly resolve references or that such references actually resolve to a parameter object.
Upon error, invoke a ErrorOnParamFunc callback with the erroneous parameters. If the callback is set to nil, panics upon errors.
func (s *Spec) SafeParamsFor(method, path string, callmeOnError ErrorOnParamFunc) map[string]spec.Parameter
SafeParamsFor the specified method and path. Aggregates them with the defaults etc, so it's all the params that apply for the method and path.
Does not assume parameters properly resolve references or that such references actually resolve to a parameter object.
Upon error, invoke a ErrorOnParamFunc callback with the erroneous parameters. If the callback is set to nil, panics upon errors.
func (s *Spec) SchemaEnums() map[string][]interface{}
SchemaEnums returns all the enums found in schemas the map is cloned to avoid accidental changes
func (s *Spec) SchemaPatterns() map[string]string
SchemaPatterns returns all the patterns found in schemas the map is cloned to avoid accidental changes
func (s *Spec) SchemasWithAllOf() (result []SchemaRef)
SchemasWithAllOf returns schema references to all schemas that are defined with an allOf key
func (s *Spec) SecurityDefinitionsFor(operation *spec.Operation) map[string]spec.SecurityScheme
SecurityDefinitionsFor gets the matching security definitions for a set of requirements
func (s *Spec) SecurityDefinitionsForRequirements(requirements []SecurityRequirement) map[string]spec.SecurityScheme
SecurityDefinitionsForRequirements gets the matching security definitions for a set of requirements
func (s *Spec) SecurityRequirementsFor(operation *spec.Operation) [][]SecurityRequirement
SecurityRequirementsFor gets the security requirements for the operation
| Name | Synopsis |
|---|---|
| .. | |