Documentation
¶
Overview ¶
Package v2 represents all Swagger / OpenAPI 2 high-level models. High-level models are easy to navigate and simple to extract what ever is required from a specification.
High-level models are backed by low-level ones. There is a 'GoLow()' method available on every high level object. 'Going Low' allows engineers to transition from a high-level or 'porcelain' API, to a low-level 'plumbing' API, which provides fine grain detail to the underlying AST powering the data, lines, columns, raw nodes etc.
IMPORTANT: As a general rule, Swagger / OpenAPI 2 should be avoided for new projects.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Definitions ¶
type Definitions struct {
Definitions map[string]*highbase.SchemaProxy
// contains filtered or unexported fields
}
Definitions is a high-level represents of a Swagger / OpenAPI 2 Definitions object, backed by a low-level one.
An object to hold data types that can be consumed and produced by operations. These data types can be primitives, arrays or models.
func NewDefinitions ¶
func NewDefinitions(definitions *low.Definitions) *Definitions
NewDefinitions will create a new high-level instance of a Definition from a low-level one.
func (*Definitions) GoLow ¶
func (d *Definitions) GoLow() *low.Definitions
GoLow returns the low-level Definitions object used to create the high-level one.
type Example ¶ added in v0.0.10
Example represents a high-level Swagger / OpenAPI 2 Example object, backed by a low level one. Allows sharing examples for operation responses
func NewExample ¶ added in v0.0.10
NewExample creates a new high-level Example instance from a low-level one.
type Header ¶
type Header struct {
Type string
Format string
Description string
Items *Items
CollectionFormat string
Default any
Maximum int
ExclusiveMaximum bool
Minimum int
ExclusiveMinimum bool
MaxLength int
MinLength int
Pattern string
MaxItems int
MinItems int
UniqueItems bool
Enum []any
MultipleOf int
Extensions map[string]any
// contains filtered or unexported fields
}
Header Represents a high-level Swagger / OpenAPI 2 Header object, backed by a low-level one. A Header is essentially identical to a Parameter, except it does not contain 'name' or 'in' properties.
type Items ¶
type Items struct {
Type string
Format string
CollectionFormat string
Items *Items
Default any
Maximum int
ExclusiveMaximum bool
Minimum int
ExclusiveMinimum bool
MaxLength int
MinLength int
Pattern string
MaxItems int
MinItems int
UniqueItems bool
Enum []any
MultipleOf int
// contains filtered or unexported fields
}
Items is a high-level representation of a Swagger / OpenAPI 2 Items object, backed by a low level one. Items is a limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body"
type Operation ¶
type Operation struct {
Tags []string
Summary string
Description string
ExternalDocs *base.ExternalDoc
OperationId string
Consumes []string
Produces []string
Parameters []*Parameter
Responses *Responses
Schemes []string
Deprecated bool
Security []*base.SecurityRequirement
Extensions map[string]any
// contains filtered or unexported fields
}
Operation represents a high-level Swagger / OpenAPI 2 Operation object, backed by a low-level one. It describes a single API operation on a path.
func NewOperation ¶
NewOperation creates a new high-level Operation instance from a low-level one.
type Parameter ¶
type Parameter struct {
Name string
In string
Type string
Format string
Description string
Required *bool
AllowEmptyValue *bool
Schema *base.SchemaProxy
Items *Items
CollectionFormat string
Default any
Maximum *int
ExclusiveMaximum *bool
Minimum *int
ExclusiveMinimum *bool
MaxLength *int
MinLength *int
Pattern string
MaxItems *int
MinItems *int
UniqueItems *bool
Enum []any
MultipleOf *int
Extensions map[string]any
// contains filtered or unexported fields
}
Parameter represents a high-level Swagger / OpenAPI 2 Parameter object, backed by a low-level one.
A unique parameter is defined by a combination of a name and location.
There are five possible parameter types.
Path
Used together with Path Templating, where the parameter value is actually part of the operation's URL.
This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
Query
Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
Header
Custom headers that are expected as part of the request.
Body
The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
Form
Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data
or both are used as the content type of the request (in Swagger's definition, the consumes property of an operation).
This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters
are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form
parameters have a different format based on the content-type used (for further details,
consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload. For example,
foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple parameters that are
being transferred.
multipart/form-data - each parameter takes a section in the payload with an internal header. For example, for
the header Content-Disposition: form-data; name="submit-name" the name of the parameter is
submit-name. This type of form parameters is more commonly used for file transfers
https://swagger.io/specification/v2/#parameterObject
func NewParameter ¶
NewParameter creates a new high-level instance of a Parameter from a low-level one.
type ParameterDefinitions ¶
type ParameterDefinitions struct {
Definitions map[string]*Parameter
// contains filtered or unexported fields
}
ParameterDefinitions is a high-level representation of a Swagger / OpenAPI 2 Parameters Definitions object that is backed by a low-level one.
ParameterDefinitions holds parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here. It does not define global operation parameters
func NewParametersDefinitions ¶
func NewParametersDefinitions(parametersDefinitions *low.ParameterDefinitions) *ParameterDefinitions
NewParametersDefinitions creates a new instance of a high-level ParameterDefinitions, from a low-level one. Every parameter is extracted asynchronously due to the potential depth
func (*ParameterDefinitions) GoLow ¶
func (p *ParameterDefinitions) GoLow() *low.ParameterDefinitions
GoLow returns the low-level ParameterDefinitions instance that backs the low-level one.
type PathItem ¶
type PathItem struct {
Ref string
Get *Operation
Put *Operation
Post *Operation
Delete *Operation
Options *Operation
Head *Operation
Patch *Operation
Parameters []*Parameter
Extensions map[string]any
// contains filtered or unexported fields
}
PathItem represents a high-level Swagger / OpenAPI 2 PathItem object backed by a low-level one.
Describes the operations available on a single path. A Path Item may be empty, due to ACL constraints. The path itself is still exposed to the tooling, but will not know which operations and parameters are available.
func NewPathItem ¶
NewPathItem will create a new high-level PathItem from a low-level one. All paths are built out asynchronously.
func (*PathItem) GetOperations ¶ added in v0.2.7
type Paths ¶
type Paths struct {
PathItems map[string]*PathItem
Extensions map[string]any
// contains filtered or unexported fields
}
Paths represents a high-level Swagger / OpenAPI Paths object, backed by a low-level one.
type Response ¶
type Response struct {
Description string
Schema *base.SchemaProxy
Headers map[string]*Header
Examples *Example
Extensions map[string]any
// contains filtered or unexported fields
}
Response is a representation of a high-level Swagger / OpenAPI 2 Response object, backed by a low-level one. Response describes a single response from an API Operation
func NewResponse ¶
NewResponse creates a new high-level instance of Response from a low level one.
type Responses ¶
type Responses struct {
Codes map[string]*Response
Default *Response
Extensions map[string]any
// contains filtered or unexported fields
}
Responses is a high-level representation of a Swagger / OpenAPI 2 Responses object, backed by a low level one.
func NewResponses ¶
NewResponses will create a new high-level instance of Responses from a low-level one.
type ResponsesDefinitions ¶
type ResponsesDefinitions struct {
Definitions map[string]*Response
// contains filtered or unexported fields
}
ResponsesDefinitions is a high-level representation of a Swagger / OpenAPI 2 Responses Definitions object. that is backed by a low-level one.
ResponsesDefinitions is an object to hold responses to be reused across operations. Response definitions can be referenced to the ones defined here. It does not define global operation responses
func NewResponsesDefinitions ¶
func NewResponsesDefinitions(responsesDefinitions *low.ResponsesDefinitions) *ResponsesDefinitions
NewResponsesDefinitions will create a new high-level instance of ResponsesDefinitions from a low-level one.
func (*ResponsesDefinitions) GoLow ¶
func (r *ResponsesDefinitions) GoLow() *low.ResponsesDefinitions
GoLow returns the low-level ResponsesDefinitions used to create the high-level one.
type Scopes ¶
Scopes is a high-level representation of a Swagger / OpenAPI 2 OAuth2 Scopes object, that is backed by a low-level one.
Scopes lists the available scopes for an OAuth2 security scheme.
type SecurityDefinitions ¶
type SecurityDefinitions struct {
Definitions map[string]*SecurityScheme
// contains filtered or unexported fields
}
SecurityDefinitions is a high-level representation of a Swagger / OpenAPI 2 Security Definitions object, that is backed by a low-level one.
A declaration of the security schemes available to be used in the specification. This does not enforce the security schemes on the operations and only serves to provide the relevant details for each scheme
func NewSecurityDefinitions ¶
func NewSecurityDefinitions(definitions *low.SecurityDefinitions) *SecurityDefinitions
NewSecurityDefinitions creates a new high-level instance of a SecurityDefinitions from a low-level one.
func (*SecurityDefinitions) GoLow ¶
func (sd *SecurityDefinitions) GoLow() *low.SecurityDefinitions
GoLow returns the low-level SecurityDefinitions instance used to create the high-level one.
type SecurityScheme ¶
type SecurityScheme struct {
Type string
Description string
Name string
In string
Flow string
AuthorizationUrl string
TokenUrl string
Scopes *Scopes
Extensions map[string]any
// contains filtered or unexported fields
}
SecurityScheme is a high-level representation of a Swagger / OpenAPI 2 SecurityScheme object backed by a low-level one.
SecurityScheme allows the definition of a security scheme that can be used by the operations. Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code)
func NewSecurityScheme ¶
func NewSecurityScheme(securityScheme *low.SecurityScheme) *SecurityScheme
NewSecurityScheme creates a new instance of SecurityScheme from a low-level one.
func (*SecurityScheme) GoLow ¶
func (s *SecurityScheme) GoLow() *low.SecurityScheme
GoLow returns the low-level SecurityScheme that was used to create the high-level one.
type Swagger ¶
type Swagger struct {
// Swagger is the version of Swagger / OpenAPI being used, extracted from the 'swagger: 2.x' definition.
Swagger string
// Info represents a specification Info definition.
// Provides metadata about the API. The metadata can be used by the clients if needed.
// - https://swagger.io/specification/v2/#infoObject
Info *base.Info
// Host is The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor
// sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used
// (including the port). The host does not support path templating.
Host string
// BasePath is The base path on which the API is served, which is relative to the host. If it is not included, the API is
// served directly under the host. The value MUST start with a leading slash (/).
// The basePath does not support path templating.
BasePath string
// Schemes represents the transfer protocol of the API. Requirements MUST be from the list: "http", "https", "ws", "wss".
// If the schemes is not included, the default scheme to be used is the one used to access
// the Swagger definition itself.
Schemes []string
// Consumes is a list of MIME types the APIs can consume. This is global to all APIs but can be overridden on
// specific API calls. Value MUST be as described under Mime Types.
Consumes []string
// Produces is a list of MIME types the APIs can produce. This is global to all APIs but can be overridden on
// specific API calls. Value MUST be as described under Mime Types.
Produces []string
// Paths are the paths and operations for the API. Perhaps the most important part of the specification.
// - https://swagger.io/specification/v2/#pathsObject
Paths *Paths
// Definitions is an object to hold data types produced and consumed by operations. It's composed of Schema instances
// - https://swagger.io/specification/v2/#definitionsObject
Definitions *Definitions
// Parameters is an object to hold parameters that can be used across operations.
// This property does not define global parameters for all operations.
// - https://swagger.io/specification/v2/#parametersDefinitionsObject
Parameters *ParameterDefinitions
// Responses is an object to hold responses that can be used across operations.
// This property does not define global responses for all operations.
// - https://swagger.io/specification/v2/#responsesDefinitionsObject
Responses *ResponsesDefinitions
// SecurityDefinitions represents security scheme definitions that can be used across the specification.
// - https://swagger.io/specification/v2/#securityDefinitionsObject
SecurityDefinitions *SecurityDefinitions
// Security is a declaration of which security schemes are applied for the API as a whole. The list of values
// describes alternative security schemes that can be used (that is, there is a logical OR between the security
// requirements). Individual operations can override this definition.
// - https://swagger.io/specification/v2/#securityRequirementObject
Security []*base.SecurityRequirement
// Tags are A list of tags used by the specification with additional metadata.
// The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used
// by the Operation Object must be declared. The tags that are not declared may be organized randomly or based
// on the tools' logic. Each tag name in the list MUST be unique.
// - https://swagger.io/specification/v2/#tagObject
Tags []*base.Tag
// ExternalDocs is an instance of base.ExternalDoc for.. well, obvious really, innit.
ExternalDocs *base.ExternalDoc
// Extensions contains all custom extensions defined for the top-level document.
Extensions map[string]any
// contains filtered or unexported fields
}
Swagger represents a high-level Swagger / OpenAPI 2 document. An instance of Swagger is the root of the specification.
func NewSwaggerDocument ¶
NewSwaggerDocument will create a new high-level Swagger document from a low-level one.
Source Files