package analysis

import "github.com/go-openapi/analysis"

Package analysis provides methods to work with a Swagger specification document from package go-openapi/spec.

## Analyzing a specification

An analysed specification object (type Spec) provides methods to work with swagger definition.

## Flattening or expanding a specification

Flattening a specification bundles all remote $ref in the main spec document. Depending on flattening options, additional preprocessing may take place:

• full flattening: replacing all inline complex constructs by a named entry in #/definitions
• expand: replace all $ref's in the document by their expanded content

## Merging several specifications

Mixin several specifications merges all Swagger constructs, and warns about found conflicts.

## Fixing a specification

Unmarshalling a specification with golang json unmarshalling may lead to some unwanted result on present but empty fields.

## Analyzing a Swagger schema

Swagger schemas are analyzed to determine their complexity and qualify their content.

Index ¶

• func FixEmptyDesc(rs *spec.Response)
• func FixEmptyDescs(rs *spec.Responses)
• func FixEmptyResponseDescriptions(s *spec.Swagger)
• func Flatten(opts FlattenOpts) error
• func GenLocation(parts sortref.SplitKey) string
• func Mixin(primary *spec.Swagger, mixins ...*spec.Swagger) []string
• type AnalyzedSchema
• func Schema(opts SchemaOpts) (*AnalyzedSchema, error)
• type ErrorOnParamFunc
• type FlattenOpts
• func (f *FlattenOpts) ExpandOpts(skipSchemas bool) *spec.ExpandOptions
• func (f *FlattenOpts) Swagger() *spec.Swagger
• type InlineSchemaNamer
• func (isn *InlineSchemaNamer) Name(key string, schema *spec.Schema, aschema *AnalyzedSchema) error
• type SchemaOpts
• type SchemaRef
• type SecurityRequirement
• type Spec
• func New(doc *spec.Swagger) *Spec
• func (s *Spec) AllDefinitionReferences() (result []string)
• func (s *Spec) AllDefinitions() (result []SchemaRef)
• func (s *Spec) AllEnums() map[string][]interface{}
• func (s *Spec) AllItemsReferences() (result []string)
• func (s *Spec) AllParameterReferences() (result []string)
• func (s *Spec) AllPathItemReferences() (result []string)
• func (s *Spec) AllPaths() map[string]spec.PathItem
• func (s *Spec) AllPatterns() map[string]string
• func (s *Spec) AllReferences() (result []string)
• func (s *Spec) AllRefs() (result []spec.Ref)
• func (s *Spec) AllResponseReferences() (result []string)
• func (s *Spec) ConsumesFor(operation *spec.Operation) []string
• func (s *Spec) HeaderEnums() map[string][]interface{}
• func (s *Spec) HeaderPatterns() map[string]string
• func (s *Spec) ItemsEnums() map[string][]interface{}
• func (s *Spec) ItemsPatterns() map[string]string
• func (s *Spec) OperationFor(method, path string) (*spec.Operation, bool)
• func (s *Spec) OperationForName(operationID string) (string, string, *spec.Operation, bool)
• func (s *Spec) OperationIDs() []string
• func (s *Spec) OperationMethodPaths() []string
• func (s *Spec) Operations() map[string]map[string]*spec.Operation
• func (s *Spec) ParameterEnums() map[string][]interface{}
• func (s *Spec) ParameterPatterns() map[string]string
• func (s *Spec) ParametersFor(operationID string) []spec.Parameter
• func (s *Spec) ParamsFor(method, path string) map[string]spec.Parameter
• func (s *Spec) ProducesFor(operation *spec.Operation) []string
• func (s *Spec) RequiredConsumes() []string
• func (s *Spec) RequiredProduces() []string
• func (s *Spec) RequiredSecuritySchemes() []string
• func (s *Spec) SafeParametersFor(operationID string, callmeOnError ErrorOnParamFunc) []spec.Parameter
• func (s *Spec) SafeParamsFor(method, path string, callmeOnError ErrorOnParamFunc) map[string]spec.Parameter
• func (s *Spec) SchemaEnums() map[string][]interface{}
• func (s *Spec) SchemaPatterns() map[string]string
• func (s *Spec) SchemasWithAllOf() (result []SchemaRef)
• func (s *Spec) SecurityDefinitionsFor(operation *spec.Operation) map[string]spec.SecurityScheme
• func (s *Spec) SecurityDefinitionsForRequirements(requirements []SecurityRequirement) map[string]spec.SecurityScheme
• func (s *Spec) SecurityRequirementsFor(operation *spec.Operation) [][]SecurityRequirement

Functions ¶

func FixEmptyDesc ¶

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 ¶

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 ¶

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 ¶

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:

• Expanding parameters, responses, path items, parameter items and header items (references to schemas are left unscathed)
• Importing external (http, file) references so they become internal to the document
• Moving every JSON pointer to a $ref to a named definition (i.e. the reworked spec does not contain pointers like "$ref": "#/definitions/myObject/allOfs/1")

A minimally flattened spec thus guarantees the following properties:

• all $refs point to a local definition (i.e. '#/definitions/...')
• definitions are unique

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:

• Moving every complex inline schema to be a definition with an auto-generated name in a depth-first fashion.

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:

• Minimal: stops flattening after minimal $ref processing, leaving schema constructs untouched
• Expand: expand all $ref's in the document (inoperant if Minimal set to true)
• Verbose: croaks about name conflicts detected
• RemoveUnused: removes unused parameters, responses and definitions after expansion/flattening

NOTE: expansion removes all $ref save circular $ref, which remain in place

TODO: additional options

• ProgagateNameExtensions: ensure that created entries properly follow naming rules when their parent have set a x-go-name extension
• LiftAllOfs:
• limit the flattening of allOf members when simple objects
• merge allOf with validation only
• merge allOf with extensions only
• ...

func GenLocation ¶

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 ¶

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

• Info
• BasePath
• Host
• ExternalDocs

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.

Types ¶

type AnalyzedSchema ¶

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
}

AnalyzedSchema indicates what the schema represents

func Schema ¶

func Schema(opts SchemaOpts) (*AnalyzedSchema, error)

Schema analysis, will classify the schema according to known patterns.

type ErrorOnParamFunc ¶

type ErrorOnParamFunc func(spec.Parameter, error) bool

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 FlattenOpts ¶

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
}

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.

func (*FlattenOpts) ExpandOpts ¶

func (f *FlattenOpts) ExpandOpts(skipSchemas bool) *spec.ExpandOptions

ExpandOpts creates a spec.ExpandOptions to configure expanding a specification document.

func (*FlattenOpts) Swagger ¶

func (f *FlattenOpts) Swagger() *spec.Swagger

Swagger gets the swagger specification for this flatten operation

type InlineSchemaNamer ¶

type InlineSchemaNamer struct {
	Spec       *spec.Swagger
	Operations map[string]operations.OpRef
	// contains filtered or unexported fields
}

InlineSchemaNamer finds a new name for an inlined type

func (*InlineSchemaNamer) Name ¶

func (isn *InlineSchemaNamer) Name(key string, schema *spec.Schema, aschema *AnalyzedSchema) error

Name yields a new name for the inline schema

type SchemaOpts ¶

type SchemaOpts struct {
	Schema   *spec.Schema
	Root     interface{}
	BasePath string
	// contains filtered or unexported fields
}

SchemaOpts configures the schema analyzer

type SchemaRef ¶

type SchemaRef struct {
	Name     string
	Ref      spec.Ref
	Schema   *spec.Schema
	TopLevel bool
}

SchemaRef is a reference to a schema

type SecurityRequirement ¶

type SecurityRequirement struct {
	Name   string
	Scopes []string
}

SecurityRequirement is a representation of a security requirement for an operation

type Spec ¶

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

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.

func New ¶

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 (*Spec) AllDefinitionReferences ¶

func (s *Spec) AllDefinitionReferences() (result []string)

AllDefinitionReferences returns json refs for all the discovered schemas

func (*Spec) AllDefinitions ¶

func (s *Spec) AllDefinitions() (result []SchemaRef)

AllDefinitions returns schema references for all the definitions that were discovered

func (*Spec) AllEnums ¶

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 (*Spec) AllItemsReferences ¶

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 (*Spec) AllParameterReferences ¶

func (s *Spec) AllParameterReferences() (result []string)

AllParameterReferences returns json refs for all the discovered parameters

func (*Spec) AllPathItemReferences ¶

func (s *Spec) AllPathItemReferences() (result []string)

AllPathItemReferences returns the references for all the items

func (*Spec) AllPaths ¶

func (s *Spec) AllPaths() map[string]spec.PathItem

AllPaths returns all the paths in the swagger spec

func (*Spec) AllPatterns ¶

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 (*Spec) AllReferences ¶

func (s *Spec) AllReferences() (result []string)

AllReferences returns all the references found in the document, with possible duplicates

func (*Spec) AllRefs ¶

func (s *Spec) AllRefs() (result []spec.Ref)

AllRefs returns all the unique references found in the document

func (*Spec) AllResponseReferences ¶

func (s *Spec) AllResponseReferences() (result []string)

AllResponseReferences returns json refs for all the discovered responses

func (*Spec) ConsumesFor ¶

func (s *Spec) ConsumesFor(operation *spec.Operation) []string

ConsumesFor gets the mediatypes for the operation

func (*Spec) HeaderEnums ¶

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 (*Spec) HeaderPatterns ¶

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 (*Spec) ItemsEnums ¶

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 (*Spec) ItemsPatterns ¶

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 (*Spec) OperationFor ¶

func (s *Spec) OperationFor(method, path string) (*spec.Operation, bool)

OperationFor the given method and path

func (*Spec) OperationForName ¶

func (s *Spec) OperationForName(operationID string) (string, string, *spec.Operation, bool)

OperationForName gets the operation for the given id

func (*Spec) OperationIDs ¶

func (s *Spec) OperationIDs() []string

OperationIDs gets all the operation ids based on method an dpath

func (*Spec) OperationMethodPaths ¶

func (s *Spec) OperationMethodPaths() []string

OperationMethodPaths gets all the operation ids based on method an dpath

func (*Spec) Operations ¶

func (s *Spec) Operations() map[string]map[string]*spec.Operation

Operations gathers all the operations specified in the spec document

func (*Spec) ParameterEnums ¶

func (s *Spec) ParameterEnums() map[string][]interface{}

ParameterEnums returns all the enums found in parameters the map is cloned to avoid accidental changes

func (*Spec) ParameterPatterns ¶

func (s *Spec) ParameterPatterns() map[string]string

ParameterPatterns returns all the patterns found in parameters the map is cloned to avoid accidental changes

func (*Spec) ParametersFor ¶

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 (*Spec) ParamsFor ¶

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 (*Spec) ProducesFor ¶

func (s *Spec) ProducesFor(operation *spec.Operation) []string

ProducesFor gets the mediatypes for the operation

func (*Spec) RequiredConsumes ¶

func (s *Spec) RequiredConsumes() []string

RequiredConsumes gets all the distinct consumes that are specified in the specification document

func (*Spec) RequiredProduces ¶

func (s *Spec) RequiredProduces() []string

RequiredProduces gets all the distinct produces that are specified in the specification document

func (*Spec) RequiredSecuritySchemes ¶

func (s *Spec) RequiredSecuritySchemes() []string

RequiredSecuritySchemes gets all the distinct security schemes that are specified in the swagger spec

func (*Spec) SafeParametersFor ¶

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 (*Spec) SafeParamsFor ¶

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 (*Spec) SchemaEnums ¶

func (s *Spec) SchemaEnums() map[string][]interface{}

SchemaEnums returns all the enums found in schemas the map is cloned to avoid accidental changes

func (*Spec) SchemaPatterns ¶

func (s *Spec) SchemaPatterns() map[string]string

SchemaPatterns returns all the patterns found in schemas the map is cloned to avoid accidental changes

func (*Spec) SchemasWithAllOf ¶

func (s *Spec) SchemasWithAllOf() (result []SchemaRef)

SchemasWithAllOf returns schema references to all schemas that are defined with an allOf key

func (*Spec) SecurityDefinitionsFor ¶

func (s *Spec) SecurityDefinitionsFor(operation *spec.Operation) map[string]spec.SecurityScheme

SecurityDefinitionsFor gets the matching security definitions for a set of requirements

func (*Spec) SecurityDefinitionsForRequirements ¶

func (s *Spec) SecurityDefinitionsForRequirements(requirements []SecurityRequirement) map[string]spec.SecurityScheme

SecurityDefinitionsForRequirements gets the matching security definitions for a set of requirements

func (*Spec) SecurityRequirementsFor ¶

func (s *Spec) SecurityRequirementsFor(operation *spec.Operation) [][]SecurityRequirement

SecurityRequirementsFor gets the security requirements for the operation

Source Files ¶

analyzer.go debug.go doc.go fixer.go flatten.go flatten_name.go flatten_options.go mixin.go schema.go

Directories ¶