Documentation
¶
Overview ¶
Package v2 represents all Swagger / OpenAPI 2 low-level models.
Low-level models are more difficult to navigate than higher-level models, however they are packed with all the raw AST and node data required to perform any kind of analysis on the underlying data.
Every property is wrapped in a NodeReference or a KeyReference or a ValueReference.
IMPORTANT: As a general rule, Swagger / OpenAPI 2 should be avoided for new projects.
Example (CreateLowLevelSwaggerDocument) ¶
How to create a low-level Swagger / OpenAPI 2 Document from a specification
// How to create a low-level OpenAPI 2 Document
// load petstore into bytes
petstoreBytes, _ := ioutil.ReadFile("../../../test_specs/petstorev2.json")
// read in specification
info, _ := datamodel.ExtractSpecInfo(petstoreBytes)
// build low-level document model
document, errors := CreateDocument(info)
// if something went wrong, a slice of errors is returned
if len(errors) > 0 {
for i := range errors {
fmt.Printf("error: %s\n", errors[i].Error())
}
panic("cannot build document")
}
// print out email address from the info > contact object.
fmt.Print(document.Info.Value.Contact.Value.Email.Value)
Output: apiteam@swagger.io
Index ¶
Examples ¶
Constants ¶
const ( DefinitionsLabel = "definitions" SecurityDefinitionsLabel = "securityDefinitions" ExamplesLabel = "examples" HeadersLabel = "headers" DefaultLabel = "default" ItemsLabel = "items" ParametersLabel = "parameters" PathsLabel = "paths" GetLabel = "get" PostLabel = "post" PatchLabel = "patch" PutLabel = "put" DeleteLabel = "delete" OptionsLabel = "options" HeadLabel = "head" SecurityLabel = "security" ScopesLabel = "scopes" ResponsesLabel = "responses" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Definitions ¶
type Definitions struct {
Schemas map[low.KeyReference[string]]low.ValueReference[*base.SchemaProxy]
}
Definitions is a low-level representation of a Swagger / OpenAPI 2 Definitions object
An object to hold data types that can be consumed and produced by operations. These data types can be primitives, arrays or models.
func (*Definitions) Build ¶
func (d *Definitions) Build(root *yaml.Node, idx *index.SpecIndex) error
Build will extract all definitions into SchemaProxy instances.
func (*Definitions) FindSchema ¶
func (d *Definitions) FindSchema(schema string) *low.ValueReference[*base.SchemaProxy]
FindSchema will attempt to locate a base.SchemaProxy instance using a name.
type Examples ¶
type Examples struct {
Values map[low.KeyReference[string]]low.ValueReference[any]
}
Examples represents a low-level Swagger / OpenAPI 2 Example object. Allows sharing examples for operation responses
func (*Examples) Build ¶
Build will extract all examples and will attempt to unmarshal content into a map or slice based on type.
func (*Examples) FindExample ¶
func (e *Examples) FindExample(name string) *low.ValueReference[any]
FindExample attempts to locate an example value, using a key label.
type Header ¶
type Header struct {
Type low.NodeReference[string]
Format low.NodeReference[string]
Description low.NodeReference[string]
Items low.NodeReference[*Items]
CollectionFormat low.NodeReference[string]
Default low.NodeReference[any]
Maximum low.NodeReference[int]
ExclusiveMaximum low.NodeReference[bool]
Minimum low.NodeReference[int]
ExclusiveMinimum low.NodeReference[bool]
MaxLength low.NodeReference[int]
MinLength low.NodeReference[int]
Pattern low.NodeReference[string]
MaxItems low.NodeReference[int]
MinItems low.NodeReference[int]
UniqueItems low.NodeReference[bool]
Enum low.NodeReference[[]low.ValueReference[string]]
MultipleOf low.NodeReference[int]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Header Represents a low-level Swagger / OpenAPI 2 Header object.
A Header is essentially identical to a Parameter, except it does not contain 'name' or 'in' properties.
func (*Header) Build ¶
Build will build out items, extensions and default value from the supplied node.
func (*Header) FindExtension ¶
func (h *Header) FindExtension(ext string) *low.ValueReference[any]
FindExtension will attempt to locate an extension value using a name lookup.
type Items ¶
type Items struct {
Type low.NodeReference[string]
Format low.NodeReference[string]
CollectionFormat low.NodeReference[string]
Items low.NodeReference[*Items]
Default low.NodeReference[any]
Maximum low.NodeReference[int]
ExclusiveMaximum low.NodeReference[bool]
Minimum low.NodeReference[int]
ExclusiveMinimum low.NodeReference[bool]
MaxLength low.NodeReference[int]
MinLength low.NodeReference[int]
Pattern low.NodeReference[string]
MaxItems low.NodeReference[int]
MinItems low.NodeReference[int]
UniqueItems low.NodeReference[bool]
Enum low.NodeReference[[]low.ValueReference[string]]
MultipleOf low.NodeReference[int]
}
Items is a low-level representation of a Swagger / OpenAPI 2 Items object.
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 low.NodeReference[[]low.ValueReference[string]]
Summary low.NodeReference[string]
Description low.NodeReference[string]
ExternalDocs low.NodeReference[*base.ExternalDoc]
OperationId low.NodeReference[string]
Consumes low.NodeReference[[]low.ValueReference[string]]
Produces low.NodeReference[[]low.ValueReference[string]]
Parameters low.NodeReference[[]low.ValueReference[*Parameter]]
Responses low.NodeReference[*Responses]
Schemes low.NodeReference[[]low.ValueReference[string]]
Deprecated low.NodeReference[bool]
Security low.NodeReference[[]low.ValueReference[*SecurityRequirement]]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Operation represents a low-level Swagger / OpenAPI 2 Operation object.
It describes a single API operation on a path.
type Parameter ¶
type Parameter struct {
Name low.NodeReference[string]
In low.NodeReference[string]
Type low.NodeReference[string]
Format low.NodeReference[string]
Description low.NodeReference[string]
Required low.NodeReference[bool]
AllowEmptyValue low.NodeReference[bool]
Schema low.NodeReference[*base.SchemaProxy]
Items low.NodeReference[*Items]
CollectionFormat low.NodeReference[string]
Default low.NodeReference[any]
Maximum low.NodeReference[int]
ExclusiveMaximum low.NodeReference[bool]
Minimum low.NodeReference[int]
ExclusiveMinimum low.NodeReference[bool]
MaxLength low.NodeReference[int]
MinLength low.NodeReference[int]
Pattern low.NodeReference[string]
MaxItems low.NodeReference[int]
MinItems low.NodeReference[int]
UniqueItems low.NodeReference[bool]
Enum low.NodeReference[[]low.ValueReference[string]]
MultipleOf low.NodeReference[int]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Parameter represents a low-level Swagger / OpenAPI 2 Parameter object.
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 (*Parameter) FindExtension ¶
func (p *Parameter) FindExtension(ext string) *low.ValueReference[any]
FindExtension attempts to locate a extension value given a name.
type ParameterDefinitions ¶
type ParameterDefinitions struct {
Definitions map[low.KeyReference[string]]low.ValueReference[*Parameter]
}
ParameterDefinitions is a low-level representation of a Swagger / OpenAPI 2 Parameters Definitions object.
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 (*ParameterDefinitions) Build ¶
func (pd *ParameterDefinitions) Build(root *yaml.Node, idx *index.SpecIndex) error
Build will extract all ParameterDefinitions into Parameter instances.
func (*ParameterDefinitions) FindParameter ¶
func (pd *ParameterDefinitions) FindParameter(parameter string) *low.ValueReference[*Parameter]
FindParameter will attempt to locate a Parameter instance using a name.
type PathItem ¶
type PathItem struct {
Ref low.NodeReference[string]
Get low.NodeReference[*Operation]
Put low.NodeReference[*Operation]
Post low.NodeReference[*Operation]
Delete low.NodeReference[*Operation]
Options low.NodeReference[*Operation]
Head low.NodeReference[*Operation]
Patch low.NodeReference[*Operation]
Parameters low.NodeReference[[]low.ValueReference[*Parameter]]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
PathItem represents a low-level Swagger / OpenAPI 2 PathItem object.
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 (*PathItem) Build ¶
Build will extract extensions, parameters and operations for all methods. Every method is handled asynchronously, in order to keep things moving quickly for complex operations.
func (*PathItem) FindExtension ¶
func (p *PathItem) FindExtension(ext string) *low.ValueReference[any]
FindExtension will attempt to locate an extension given a name.
type Paths ¶
type Paths struct {
PathItems map[low.KeyReference[string]]low.ValueReference[*PathItem]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Paths represents a low-level Swagger / OpenAPI Paths object.
func (*Paths) FindExtension ¶
func (p *Paths) FindExtension(ext string) *low.ValueReference[any]
FindExtension will attempt to locate an extension value given a name.
type Response ¶
type Response struct {
Description low.NodeReference[string]
Schema low.NodeReference[*base.SchemaProxy]
Headers low.NodeReference[map[low.KeyReference[string]]low.ValueReference[*Header]]
Examples low.NodeReference[*Examples]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
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 (*Response) FindExtension ¶
func (r *Response) FindExtension(ext string) *low.ValueReference[any]
FindExtension will attempt to locate an extension value given a key to lookup.
func (*Response) FindHeader ¶
func (r *Response) FindHeader(hType string) *low.ValueReference[*Header]
FindHeader will attempt to locate a Header value, given a key
type Responses ¶
type Responses struct {
Codes map[low.KeyReference[string]]low.ValueReference[*Response]
Default low.NodeReference[*Response]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Responses is a low-level representation of a Swagger / OpenAPI 2 Responses object.
func (*Responses) FindResponseByCode ¶
func (r *Responses) FindResponseByCode(code string) *low.ValueReference[*Response]
FindResponseByCode will attempt to locate a Response instance using an HTTP response code string.
type ResponsesDefinitions ¶
type ResponsesDefinitions struct {
Definitions map[low.KeyReference[string]]low.ValueReference[*Response]
}
ResponsesDefinitions is a low-level representation of a Swagger / OpenAPI 2 Responses Definitions object.
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 (*ResponsesDefinitions) Build ¶
func (r *ResponsesDefinitions) Build(root *yaml.Node, idx *index.SpecIndex) error
Build will extract all ResponsesDefinitions into Response instances.
func (*ResponsesDefinitions) FindResponse ¶
func (r *ResponsesDefinitions) FindResponse(response string) *low.ValueReference[*Response]
FindResponse will attempt to locate a Response instance using a name.
type Scopes ¶
type Scopes struct {
Values map[low.KeyReference[string]]low.ValueReference[string]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
Scopes is a low-level representation of a Swagger / OpenAPI 2 OAuth2 Scopes object.
Scopes lists the available scopes for an OAuth2 security scheme.
type SecurityDefinitions ¶
type SecurityDefinitions struct {
Definitions map[low.KeyReference[string]]low.ValueReference[*SecurityScheme]
}
SecurityDefinitions is a low-level representation of a Swagger / OpenAPI 2 Security Definitions object.
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 (*SecurityDefinitions) Build ¶
func (s *SecurityDefinitions) Build(root *yaml.Node, idx *index.SpecIndex) error
Build will extract all SecurityDefinitions into SecurityScheme instances.
func (*SecurityDefinitions) FindSecurityDefinition ¶
func (s *SecurityDefinitions) FindSecurityDefinition(securityDef string) *low.ValueReference[*SecurityScheme]
FindSecurityDefinition will attempt to locate a SecurityScheme using a name.
type SecurityRequirement ¶
type SecurityRequirement struct {
Values low.ValueReference[map[low.KeyReference[string]]low.ValueReference[[]low.ValueReference[string]]]
}
SecurityRequirement is a low-level representation of a Swagger / OpenAPI 2 SecurityRequirement object.
SecurityRequirement lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes).
The name used for each property MUST correspond to a security scheme declared in the Security Definitions
type SecurityScheme ¶
type SecurityScheme struct {
Type low.NodeReference[string]
Description low.NodeReference[string]
Name low.NodeReference[string]
In low.NodeReference[string]
Flow low.NodeReference[string]
AuthorizationUrl low.NodeReference[string]
TokenUrl low.NodeReference[string]
Scopes low.NodeReference[*Scopes]
Extensions map[low.KeyReference[string]]low.ValueReference[any]
}
SecurityScheme is a low-level representation of a Swagger / OpenAPI 2 SecurityScheme object.
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)
type Swagger ¶
type Swagger struct {
// Swagger is the version of Swagger / OpenAPI being used, extracted from the 'swagger: 2.x' definition.
Swagger low.ValueReference[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 low.NodeReference[*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 low.NodeReference[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 low.NodeReference[string]
// Schemes represents the transfer protocol of the API. Values 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 low.NodeReference[[]low.ValueReference[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 low.NodeReference[[]low.ValueReference[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 low.NodeReference[[]low.ValueReference[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 low.NodeReference[*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 low.NodeReference[*Definitions]
// SecurityDefinitions represents security scheme definitions that can be used across the specification.
// - https://swagger.io/specification/v2/#securityDefinitionsObject
SecurityDefinitions low.NodeReference[*SecurityDefinitions]
// 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 low.NodeReference[*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 low.NodeReference[*ResponsesDefinitions]
// 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 low.NodeReference[[]low.ValueReference[*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 low.NodeReference[[]low.ValueReference[*base.Tag]]
// ExternalDocs is an instance of base.ExternalDoc for.. well, obvious really, innit mate?
ExternalDocs low.NodeReference[*base.ExternalDoc]
// Extensions contains all custom extensions defined for the top-level document.
Extensions map[low.KeyReference[string]]low.ValueReference[any]
// Index is a reference to the index.SpecIndex that was created for the document and used
// as a guide when building out the Document. Ideal if further processing is required on the model and
// the original details are required to continue the work.
//
// This property is not a part of the OpenAPI schema, this is custom to libopenapi.
Index *index.SpecIndex
// SpecInfo is a reference to the datamodel.SpecInfo instance created when the specification was read.
//
// This property is not a part of the OpenAPI schema, this is custom to libopenapi.
SpecInfo *datamodel.SpecInfo
}
Swagger represents a high-level Swagger / OpenAPI 2 document. An instance of Swagger is the root of the specification.
func CreateDocument ¶
Example ¶
How to create a low-level Swagger / OpenAPI 2 Document from a specification
// How to create a low-level OpenAPI 2 Document
// load petstore into bytes
petstoreBytes, _ := ioutil.ReadFile("../../../test_specs/petstorev2.json")
// read in specification
info, _ := datamodel.ExtractSpecInfo(petstoreBytes)
// build low-level document model
document, errors := CreateDocument(info)
// if something went wrong, a slice of errors is returned
if len(errors) > 0 {
for i := range errors {
fmt.Printf("error: %s\n", errors[i].Error())
}
panic("cannot build document")
}
// print out email address from the info > contact object.
fmt.Print(document.Info.Value.Contact.Value.Email.Value)
Output: apiteam@swagger.io
func (*Swagger) FindExtension ¶
func (s *Swagger) FindExtension(ext string) *low.ValueReference[any]
FindExte
Source Files