swagger

package
v1.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2025 License: MIT Imports: 23 Imported by: 1

README

Swagger

Swagger Parser

An API for working with Swagger Documents including: read, walk, create, mutate, and validate

Built by Speakeasy Release Go Doc
Go Report Card Software License

Contributing

This repository is maintained by Speakeasy, but we welcome and encourage contributions from the community to help improve its capabilities and stability.

How to Contribute

  1. Open Issues: Found a bug or have a feature suggestion? Open an issue to describe what you'd like to see changed.

  2. Pull Requests: We welcome pull requests! If you'd like to contribute code:

    • Fork the repository
    • Create a new branch for your feature/fix
    • Submit a PR with a clear description of the changes and any related issues

  3. Feedback: Share your experience using the packages or suggest improvements.

All contributions, whether they're bug reports, feature requests, or code changes, help make this project better for everyone.

Please ensure your contributions adhere to our coding standards and include appropriate tests where applicable.

Documentation

Index

Constants

View Source 
const Version = "2.0"

Version is the Swagger specification version supported by this package.

Variables

This section is empty.

Functions

func Marshal 

func Marshal(ctx context.Context, swagger *Swagger, w io.Writer) error

Marshal will marshal the provided Swagger document to the provided io.Writer.

func Sync 

func Sync(ctx context.Context, model marshaller.Marshallable[core.Swagger]) error

Sync will sync the high-level model to the core model. This is useful when creating or mutating a high-level model and wanting access to the yaml nodes that back it.

func Upgrade 

func Upgrade(ctx context.Context, src *Swagger) (*openapi.OpenAPI, error)

Upgrade converts a Swagger 2.0 document into an OpenAPI 3.0 document.

The conversion performs the following major transformations: - swagger: "2.0" -> openapi: "3.0.0" - host/basePath/schemes -> servers - definitions -> components.schemas - parameters (global non-body) -> components.parameters - parameters (global body) -> components.requestBodies - responses (global) -> components.responses - securityDefinitions -> components.securitySchemes - operation parameters:

  • in: body -> requestBody with content and schema
  • in: formData -> requestBody with x-www-form-urlencoded or multipart/form-data schema
  • other parameters carried over with schema and style/explode derived from collectionFormat

- responses: schema/examples -> content[mediaType].schema/example - Rewrites JSON Schema $ref targets from "#/definitions/..." to "#/components/schemas/..."

func Walk 

func Walk[T any](ctx context.Context, start *T) iter.Seq[WalkItem]

Walk returns an iterator that yields MatchFunc items for each model in the provided Swagger model. Users can iterate over the results using a for loop and break out at any time. When called with *Swagger, it walks the entire document. When called with other types, it walks from that specific component.

Types

type CollectionFormat 

type CollectionFormat string

CollectionFormat represents how array parameters are serialized. 

const (
	// CollectionFormatCSV represents comma-separated values.
	CollectionFormatCSV CollectionFormat = "csv"
	// CollectionFormatSSV represents space-separated values.
	CollectionFormatSSV CollectionFormat = "ssv"
	// CollectionFormatTSV represents tab-separated values.
	CollectionFormatTSV CollectionFormat = "tsv"
	// CollectionFormatPipes represents pipe-separated values.
	CollectionFormatPipes CollectionFormat = "pipes"
	// CollectionFormatMulti represents multiple parameter instances.
	CollectionFormatMulti CollectionFormat = "multi"
)

type Contact 

type Contact struct {
	marshaller.Model[core.Contact]

	// Name is the identifying name of the contact person/organization.
	Name *string
	// URL is the URL pointing to the contact information. MUST be in the format of a URL.
	URL *string
	// Email is the email address of the contact person/organization. MUST be in the format of an email address.
	Email *string
	// Extensions provides a list of extensions to the Contact object.
	Extensions *extensions.Extensions
}

Contact information for the exposed API.

func (*Contact) GetEmail 

func (c *Contact) GetEmail() string

GetEmail returns the value of the Email field. Returns empty string if not set.

func (*Contact) GetExtensions 

func (c *Contact) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Contact) GetName 

func (c *Contact) GetName() string

GetName returns the value of the Name field. Returns empty string if not set.

func (*Contact) GetURL 

func (c *Contact) GetURL() string

GetURL returns the value of the URL field. Returns empty string if not set.

func (*Contact) Validate 

func (c *Contact) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Contact object against the Swagger Specification.

type ExternalDocumentation 

type ExternalDocumentation struct {
	marshaller.Model[core.ExternalDocumentation]

	// Description is a short description of the target documentation. GFM syntax can be used for rich text representation.
	Description *string
	// URL is the URL for the target documentation. MUST be in the format of a URL.
	URL string
	// Extensions provides a list of extensions to the ExternalDocumentation object.
	Extensions *extensions.Extensions
}

ExternalDocumentation allows referencing an external resource for extended documentation.

func (*ExternalDocumentation) GetDescription 

func (e *ExternalDocumentation) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*ExternalDocumentation) GetExtensions 

func (e *ExternalDocumentation) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*ExternalDocumentation) GetURL 

func (e *ExternalDocumentation) GetURL() string

GetURL returns the value of the URL field. Returns empty string if not set.

func (*ExternalDocumentation) Validate 

func (e *ExternalDocumentation) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the ExternalDocumentation object against the Swagger Specification.

type HTTPMethod 

type HTTPMethod string

HTTPMethod is an enum representing the HTTP methods available in the Swagger specification. 

const (
	// HTTPMethodGet represents the HTTP GET method.
	HTTPMethodGet HTTPMethod = "get"
	// HTTPMethodPut represents the HTTP PUT method.
	HTTPMethodPut HTTPMethod = "put"
	// HTTPMethodPost represents the HTTP POST method.
	HTTPMethodPost HTTPMethod = "post"
	// HTTPMethodDelete represents the HTTP DELETE method.
	HTTPMethodDelete HTTPMethod = "delete"
	// HTTPMethodOptions represents the HTTP OPTIONS method.
	HTTPMethodOptions HTTPMethod = "options"
	// HTTPMethodHead represents the HTTP HEAD method.
	HTTPMethodHead HTTPMethod = "head"
	// HTTPMethodPatch represents the HTTP PATCH method.
	HTTPMethodPatch HTTPMethod = "patch"
)
type Header struct {
	marshaller.Model[core.Header]

	// Description is a short description of the header.
	Description *string
	// Type is the type of the object.
	Type string
	// Format is the extending format for the type.
	Format *string
	// Items describes the type of items in the array (if type is array).
	Items *Items
	// CollectionFormat determines the format of the array.
	CollectionFormat *CollectionFormat
	// Default declares the value the server will use if none is provided.
	Default values.Value
	// Maximum specifies the maximum value.
	Maximum *float64
	// ExclusiveMaximum specifies if maximum is exclusive.
	ExclusiveMaximum *bool
	// Minimum specifies the minimum value.
	Minimum *float64
	// ExclusiveMinimum specifies if minimum is exclusive.
	ExclusiveMinimum *bool
	// MaxLength specifies the maximum length.
	MaxLength *int64
	// MinLength specifies the minimum length.
	MinLength *int64
	// Pattern specifies a regex pattern the string must match.
	Pattern *string
	// MaxItems specifies the maximum number of items in an array.
	MaxItems *int64
	// MinItems specifies the minimum number of items in an array.
	MinItems *int64
	// UniqueItems specifies if all items must be unique.
	UniqueItems *bool
	// Enum specifies a list of allowed values.
	Enum []values.Value
	// MultipleOf specifies the value must be a multiple of this number.
	MultipleOf *float64

	// Extensions provides a list of extensions to the Header object.
	Extensions *extensions.Extensions
}

Header describes a single header in a response.

func (*Header) GetDescription 

func (h *Header) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Header) GetExtensions 

func (h *Header) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Header) GetType 

func (h *Header) GetType() string

GetType returns the value of the Type field. Returns empty string if not set.

func (*Header) Validate 

func (h *Header) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Header object against the Swagger Specification.

type Info 

type Info struct {
	marshaller.Model[core.Info]

	// Title is the title of the application.
	Title string
	// Description is a short description of the application. GFM syntax can be used for rich text representation.
	Description *string
	// TermsOfService is the Terms of Service for the API.
	TermsOfService *string
	// Contact is the contact information for the exposed API.
	Contact *Contact
	// License is the license information for the exposed API.
	License *License
	// Version provides the version of the application API (not to be confused with the specification version).
	Version string
	// Extensions provides a list of extensions to the Info object.
	Extensions *extensions.Extensions
}

Info provides metadata about the API.

func (*Info) GetContact 

func (i *Info) GetContact() *Contact

GetContact returns the value of the Contact field. Returns nil if not set.

func (*Info) GetDescription 

func (i *Info) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Info) GetExtensions 

func (i *Info) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Info) GetLicense 

func (i *Info) GetLicense() *License

GetLicense returns the value of the License field. Returns nil if not set.

func (*Info) GetTermsOfService 

func (i *Info) GetTermsOfService() string

GetTermsOfService returns the value of the TermsOfService field. Returns empty string if not set.

func (*Info) GetTitle 

func (i *Info) GetTitle() string

GetTitle returns the value of the Title field. Returns empty string if not set.

func (*Info) GetVersion 

func (i *Info) GetVersion() string

GetVersion returns the value of the Version field. Returns empty string if not set.

func (*Info) Validate 

func (i *Info) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Info object against the Swagger Specification.

type Items 

type Items struct {
	marshaller.Model[core.Items]

	// Type is the internal type of the array.
	Type string
	// Format is the extending format for the type.
	Format *string
	// Items describes the type of items in nested arrays.
	Items *Items
	// CollectionFormat determines the format of the array.
	CollectionFormat *CollectionFormat
	// Default declares the value the server will use if none is provided.
	Default values.Value
	// Maximum specifies the maximum value.
	Maximum *float64
	// ExclusiveMaximum specifies if maximum is exclusive.
	ExclusiveMaximum *bool
	// Minimum specifies the minimum value.
	Minimum *float64
	// ExclusiveMinimum specifies if minimum is exclusive.
	ExclusiveMinimum *bool
	// MaxLength specifies the maximum length.
	MaxLength *int64
	// MinLength specifies the minimum length.
	MinLength *int64
	// Pattern specifies a regex pattern the string must match.
	Pattern *string
	// MaxItems specifies the maximum number of items in an array.
	MaxItems *int64
	// MinItems specifies the minimum number of items in an array.
	MinItems *int64
	// UniqueItems specifies if all items must be unique.
	UniqueItems *bool
	// Enum specifies a list of allowed values.
	Enum []values.Value
	// MultipleOf specifies the value must be a multiple of this number.
	MultipleOf *float64

	// Extensions provides a list of extensions to the Items object.
	Extensions *extensions.Extensions
}

Items is a limited subset of JSON-Schema's items object for array parameters.

func (*Items) GetExtensions 

func (i *Items) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Items) GetType 

func (i *Items) GetType() string

GetType returns the value of the Type field. Returns empty string if not set.

func (*Items) Validate 

func (i *Items) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Items object against the Swagger Specification.

type License 

type License struct {
	marshaller.Model[core.License]

	// Name is the license name used for the API.
	Name string
	// URL is a URL to the license used for the API. MUST be in the format of a URL.
	URL *string
	// Extensions provides a list of extensions to the License object.
	Extensions *extensions.Extensions
}

License information for the exposed API.

func (*License) GetExtensions 

func (l *License) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*License) GetName 

func (l *License) GetName() string

GetName returns the value of the Name field. Returns empty string if not set.

func (*License) GetURL 

func (l *License) GetURL() string

GetURL returns the value of the URL field. Returns empty string if not set.

func (*License) Validate 

func (l *License) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the License object against the Swagger Specification.

type LocationContext 

type LocationContext = walkpkg.LocationContext[MatchFunc]

Use the shared walking infrastructure

type Locations 

type Locations = walkpkg.Locations[MatchFunc]

Use the shared walking infrastructure

type MatchFunc 

type MatchFunc func(Matcher) error

MatchFunc represents a particular model in the Swagger document that can be matched. Pass it a Matcher with the appropriate functions populated to match the model type(s) you are interested in.

type Matcher 

type Matcher struct {
	Swagger             func(*Swagger) error
	Info                func(*Info) error
	Contact             func(*Contact) error
	License             func(*License) error
	ExternalDocs        func(*ExternalDocumentation) error
	Tag                 func(*Tag) error
	Paths               func(*Paths) error
	PathItem            func(*PathItem) error
	Operation           func(*Operation) error
	ReferencedParameter func(*ReferencedParameter) error
	Parameter           func(*Parameter) error
	Schema              func(*oas3.JSONSchema[oas3.Concrete]) error
	Discriminator       func(*oas3.Discriminator) error
	XML                 func(*oas3.XML) error
	Responses           func(*Responses) error
	ReferencedResponse  func(*ReferencedResponse) error
	Response            func(*Response) error
	Header              func(*Header) error
	Items               func(*Items) error
	SecurityRequirement func(*SecurityRequirement) error
	SecurityScheme      func(*SecurityScheme) error
	Extensions          func(*extensions.Extensions) error
	Any                 func(any) error // Any will be called along with the other functions above on a match of a model
}

Matcher is a struct that can be used to match specific nodes in the Swagger document.

type OAuth2Flow 

type OAuth2Flow string

OAuth2Flow represents the flow type for OAuth2. 

const (
	// OAuth2FlowImplicit represents the implicit flow.
	OAuth2FlowImplicit OAuth2Flow = "implicit"
	// OAuth2FlowPassword represents the password flow.
	OAuth2FlowPassword OAuth2Flow = "password"
	// OAuth2FlowApplication represents the application flow.
	OAuth2FlowApplication OAuth2Flow = "application"
	// OAuth2FlowAccessCode represents the access code flow.
	OAuth2FlowAccessCode OAuth2Flow = "accessCode"
)

type Operation 

type Operation struct {
	marshaller.Model[core.Operation]

	// Tags is a list of tags for API documentation control.
	Tags []string
	// Summary is a short summary of what the operation does.
	Summary *string
	// Description is a verbose explanation of the operation behavior.
	Description *string
	// ExternalDocs is additional external documentation for this operation.
	ExternalDocs *ExternalDocumentation
	// OperationID is a unique string used to identify the operation.
	OperationID *string
	// Consumes is a list of MIME types the operation can consume.
	Consumes []string
	// Produces is a list of MIME types the operation can produce.
	Produces []string
	// Parameters is a list of parameters that are applicable for this operation.
	Parameters []*ReferencedParameter
	// Responses is the list of possible responses as they are returned from executing this operation.
	Responses *Responses
	// Schemes is the transfer protocol for the operation.
	Schemes []string
	// Deprecated declares this operation to be deprecated.
	Deprecated *bool
	// Security is a declaration of which security schemes are applied for this operation.
	Security []*SecurityRequirement
	// Extensions provides a list of extensions to the Operation object.
	Extensions *extensions.Extensions
}

Operation describes a single API operation on a path.

func (*Operation) GetConsumes 

func (o *Operation) GetConsumes() []string

GetConsumes returns the value of the Consumes field. Returns nil if not set.

func (*Operation) GetDeprecated 

func (o *Operation) GetDeprecated() bool

GetDeprecated returns the value of the Deprecated field. False by default if not set.

func (*Operation) GetDescription 

func (o *Operation) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Operation) GetExtensions 

func (o *Operation) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Operation) GetExternalDocs 

func (o *Operation) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the value of the ExternalDocs field. Returns nil if not set.

func (*Operation) GetOperationID 

func (o *Operation) GetOperationID() string

GetOperationID returns the value of the OperationID field. Returns empty string if not set.

func (*Operation) GetParameters 

func (o *Operation) GetParameters() []*ReferencedParameter

GetParameters returns the value of the Parameters field. Returns nil if not set.

func (*Operation) GetProduces 

func (o *Operation) GetProduces() []string

GetProduces returns the value of the Produces field. Returns nil if not set.

func (*Operation) GetResponses 

func (o *Operation) GetResponses() *Responses

GetResponses returns the value of the Responses field. Returns nil if not set.

func (*Operation) GetSchemes 

func (o *Operation) GetSchemes() []string

GetSchemes returns the value of the Schemes field. Returns nil if not set.

func (*Operation) GetSecurity 

func (o *Operation) GetSecurity() []*SecurityRequirement

GetSecurity returns the value of the Security field. Returns nil if not set.

func (*Operation) GetSummary 

func (o *Operation) GetSummary() string

GetSummary returns the value of the Summary field. Returns empty string if not set.

func (*Operation) GetTags 

func (o *Operation) GetTags() []string

GetTags returns the value of the Tags field. Returns nil if not set.

func (*Operation) Validate 

func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Operation object against the Swagger Specification.

type Option 

type Option[T any] func(o *T)

func WithSkipValidation 

func WithSkipValidation() Option[UnmarshalOptions]

WithSkipValidation will skip validation of the Swagger document during unmarshaling. Useful to quickly load a document that will be mutated and validated later.

type Parameter 

type Parameter struct {
	marshaller.Model[core.Parameter]

	// Name is the name of the parameter.
	Name string
	// In is the location of the parameter.
	In ParameterIn
	// Description is a brief description of the parameter.
	Description *string
	// Required determines whether this parameter is mandatory.
	Required *bool

	// For body parameters
	// Schema is the schema defining the type used for the body parameter.
	Schema *oas3.JSONSchema[oas3.Referenceable]

	// For non-body parameters
	// Type is the type of the parameter.
	Type *string
	// Format is the extending format for the type.
	Format *string
	// AllowEmptyValue sets the ability to pass empty-valued parameters (query or formData only).
	AllowEmptyValue *bool
	// Items describes the type of items in the array (if type is array).
	Items *Items
	// CollectionFormat determines the format of the array.
	CollectionFormat *CollectionFormat
	// Default declares the value the server will use if none is provided.
	Default values.Value
	// Maximum specifies the maximum value.
	Maximum *float64
	// ExclusiveMaximum specifies if maximum is exclusive.
	ExclusiveMaximum *bool
	// Minimum specifies the minimum value.
	Minimum *float64
	// ExclusiveMinimum specifies if minimum is exclusive.
	ExclusiveMinimum *bool
	// MaxLength specifies the maximum length.
	MaxLength *int64
	// MinLength specifies the minimum length.
	MinLength *int64
	// Pattern specifies a regex pattern the string must match.
	Pattern *string
	// MaxItems specifies the maximum number of items in an array.
	MaxItems *int64
	// MinItems specifies the minimum number of items in an array.
	MinItems *int64
	// UniqueItems specifies if all items must be unique.
	UniqueItems *bool
	// Enum specifies a list of allowed values.
	Enum []values.Value
	// MultipleOf specifies the value must be a multiple of this number.
	MultipleOf *float64

	// Extensions provides a list of extensions to the Parameter object.
	Extensions *extensions.Extensions
}

Parameter describes a single operation parameter.

func (*Parameter) GetDescription 

func (p *Parameter) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Parameter) GetExtensions 

func (p *Parameter) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Parameter) GetIn 

func (p *Parameter) GetIn() ParameterIn

GetIn returns the value of the In field.

func (*Parameter) GetName 

func (p *Parameter) GetName() string

GetName returns the value of the Name field. Returns empty string if not set.

func (*Parameter) GetRequired 

func (p *Parameter) GetRequired() bool

GetRequired returns the value of the Required field. False by default if not set.

func (*Parameter) GetSchema 

func (p *Parameter) GetSchema() *oas3.JSONSchema[oas3.Referenceable]

GetSchema returns the value of the Schema field. Returns nil if not set.

func (*Parameter) GetType 

func (p *Parameter) GetType() string

GetType returns the value of the Type field. Returns empty string if not set.

func (*Parameter) Validate 

func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Parameter object against the Swagger Specification.

type ParameterIn 

type ParameterIn string

ParameterIn represents the location of a parameter. 

const (
	// ParameterInQuery represents a query parameter.
	ParameterInQuery ParameterIn = "query"
	// ParameterInHeader represents a header parameter.
	ParameterInHeader ParameterIn = "header"
	// ParameterInPath represents a path parameter.
	ParameterInPath ParameterIn = "path"
	// ParameterInFormData represents a form data parameter.
	ParameterInFormData ParameterIn = "formData"
	// ParameterInBody represents a body parameter.
	ParameterInBody ParameterIn = "body"
)

type PathItem 

type PathItem struct {
	marshaller.Model[core.PathItem]
	*sequencedmap.Map[HTTPMethod, *Operation]

	// Ref allows for an external definition of this path item.
	Ref *string
	// Parameters is a list of parameters that are applicable for all operations in this path.
	Parameters []*ReferencedParameter
	// Extensions provides a list of extensions to the PathItem object.
	Extensions *extensions.Extensions
}

PathItem describes the operations available on a single path.

func NewPathItem 

func NewPathItem() *PathItem

NewPathItem creates a new PathItem object with an initialized map.

func (*PathItem) Delete 

func (p *PathItem) Delete() *Operation

Delete returns the DELETE operation for this path item.

func (*PathItem) Get 

func (p *PathItem) Get() *Operation

Get returns the GET operation for this path item.

func (*PathItem) GetExtensions 

func (p *PathItem) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*PathItem) GetOperation 

func (p *PathItem) GetOperation(method HTTPMethod) *Operation

GetOperation returns the operation for the specified HTTP method.

func (*PathItem) GetParameters 

func (p *PathItem) GetParameters() []*ReferencedParameter

GetParameters returns the value of the Parameters field. Returns nil if not set.

func (*PathItem) GetRef 

func (p *PathItem) GetRef() string

GetRef returns the value of the Ref field. Returns empty string if not set.

func (*PathItem) Head 

func (p *PathItem) Head() *Operation

Head returns the HEAD operation for this path item.

func (*PathItem) Options 

func (p *PathItem) Options() *Operation

Options returns the OPTIONS operation for this path item.

func (*PathItem) Patch 

func (p *PathItem) Patch() *Operation

Patch returns the PATCH operation for this path item.

func (*PathItem) Post 

func (p *PathItem) Post() *Operation

Post returns the POST operation for this path item.

func (*PathItem) Put 

func (p *PathItem) Put() *Operation

Put returns the PUT operation for this path item.

func (*PathItem) Validate 

func (p *PathItem) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the PathItem object according to the Swagger Specification.

type Paths 

type Paths struct {
	marshaller.Model[core.Paths]
	*sequencedmap.Map[string, *PathItem]

	// Extensions provides a list of extensions to the Paths object.
	Extensions *extensions.Extensions
}

Paths holds the relative paths to the individual endpoints.

func NewPaths 

func NewPaths() *Paths

NewPaths creates a new Paths object with an initialized map.

func (*Paths) GetExtensions 

func (p *Paths) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Paths) Validate 

func (p *Paths) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Paths object according to the Swagger Specification.

type Reference 

type Reference[T any, V interfaces.Validator[T], C marshaller.CoreModeler] struct {
	marshaller.Model[core.Reference[C]]

	// Reference is the reference string ($ref).
	Reference *references.Reference

	// If this was an inline object instead of a reference this will contain that object.
	Object *T
}

Reference represents an object that can either be referenced from elsewhere or declared inline.

func (*Reference[T, V, C]) GetObject 

func (r *Reference[T, V, C]) GetObject() *T

GetObject returns the referenced object. If this is a reference, this will return nil.

func (*Reference[T, V, C]) GetReference 

func (r *Reference[T, V, C]) GetReference() references.Reference

GetReference returns the value of the Reference field. Returns empty string if not set.

func (*Reference[T, V, C]) IsReference 

func (r *Reference[T, V, C]) IsReference() bool

IsReference returns true if the reference is a reference (via $ref) to an object as opposed to an inline object.

func (*Reference[T, V, C]) Populate 

func (r *Reference[T, V, C]) Populate(source any) error

func (*Reference[T, V, C]) Validate 

func (r *Reference[T, V, C]) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Reference object against the Swagger Specification.

type ReferencedParameter 

type ReferencedParameter = Reference[Parameter, *Parameter, *core.Parameter]

ReferencedParameter represents a parameter that can either be referenced from elsewhere or declared inline.

func NewReferencedParameterFromParameter 

func NewReferencedParameterFromParameter(parameter *Parameter) *ReferencedParameter

NewReferencedParameterFromParameter creates a new ReferencedParameter from a Parameter.

func NewReferencedParameterFromRef 

func NewReferencedParameterFromRef(ref references.Reference) *ReferencedParameter

NewReferencedParameterFromRef creates a new ReferencedParameter from a reference string.

type ReferencedResponse 

type ReferencedResponse = Reference[Response, *Response, *core.Response]

ReferencedResponse represents a response that can either be referenced from elsewhere or declared inline.

func NewReferencedResponseFromRef 

func NewReferencedResponseFromRef(ref references.Reference) *ReferencedResponse

NewReferencedResponseFromRef creates a new ReferencedResponse from a reference string.

func NewReferencedResponseFromResponse 

func NewReferencedResponseFromResponse(response *Response) *ReferencedResponse

NewReferencedResponseFromResponse creates a new ReferencedResponse from a Response.

type Response 

type Response struct {
	marshaller.Model[core.Response]

	// Description is a short description of the response.
	Description string
	// Schema is a definition of the response structure.
	Schema *oas3.JSONSchema[oas3.Referenceable]
	// Headers is a list of headers that are sent with the response.
	Headers *sequencedmap.Map[string, *Header]
	// Examples is an example of the response message.
	Examples *sequencedmap.Map[string, values.Value]
	// Extensions provides a list of extensions to the Response object.
	Extensions *extensions.Extensions
}

Response describes a single response from an API operation.

func (*Response) GetDescription 

func (r *Response) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Response) GetExamples 

func (r *Response) GetExamples() *sequencedmap.Map[string, values.Value]

GetExamples returns the value of the Examples field. Returns nil if not set.

func (*Response) GetExtensions 

func (r *Response) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Response) GetHeaders 

func (r *Response) GetHeaders() *sequencedmap.Map[string, *Header]

GetHeaders returns the value of the Headers field. Returns nil if not set.

func (*Response) GetSchema 

func (r *Response) GetSchema() *oas3.JSONSchema[oas3.Referenceable]

GetSchema returns the value of the Schema field. Returns nil if not set.

func (*Response) Validate 

func (r *Response) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Response object against the Swagger Specification.

type Responses 

type Responses struct {
	marshaller.Model[core.Responses]
	*sequencedmap.Map[string, *ReferencedResponse]

	// Default is the documentation of responses other than the ones declared for specific HTTP response codes.
	Default *ReferencedResponse
	// Extensions provides a list of extensions to the Responses object.
	Extensions *extensions.Extensions
}

Responses is a container for the expected responses of an operation.

func NewResponses 

func NewResponses() *Responses

NewResponses creates a new Responses object with an initialized map.

func (*Responses) GetDefault 

func (r *Responses) GetDefault() *ReferencedResponse

GetDefault returns the value of the Default field. Returns nil if not set.

func (*Responses) GetExtensions 

func (r *Responses) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Responses) Validate 

func (r *Responses) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Responses object against the Swagger Specification.

type SecurityRequirement 

type SecurityRequirement struct {
	marshaller.Model[core.SecurityRequirement]
	*sequencedmap.Map[string, []string]
}

SecurityRequirement lists the required security schemes to execute an operation. The keys are the names of security schemes and the values are lists of scope names. For non-oauth2 security schemes, the array MUST be empty.

func NewSecurityRequirement 

func NewSecurityRequirement() *SecurityRequirement

NewSecurityRequirement creates a new SecurityRequirement with an initialized map.

func (*SecurityRequirement) Validate 

func (s *SecurityRequirement) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the SecurityRequirement object against the Swagger Specification.

type SecurityScheme 

type SecurityScheme struct {
	marshaller.Model[core.SecurityScheme]

	// Type is the type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
	Type SecuritySchemeType
	// Description is a short description for security scheme.
	Description *string
	// Name is the name of the header or query parameter to be used (apiKey only).
	Name *string
	// In is the location of the API key. Valid values are "query" or "header" (apiKey only).
	In *SecuritySchemeIn
	// Flow is the flow used by the OAuth2 security scheme. Valid values are "implicit", "password", "application" or "accessCode" (oauth2 only).
	Flow *OAuth2Flow
	// AuthorizationURL is the authorization URL to be used for this flow (oauth2 "implicit" and "accessCode" only).
	AuthorizationURL *string
	// TokenURL is the token URL to be used for this flow (oauth2 "password", "application" and "accessCode" only).
	TokenURL *string
	// Scopes lists the available scopes for the OAuth2 security scheme (oauth2 only).
	Scopes *sequencedmap.Map[string, string]
	// Extensions provides a list of extensions to the SecurityScheme object.
	Extensions *extensions.Extensions
}

SecurityScheme defines a security scheme that can be used by the operations.

func (*SecurityScheme) GetAuthorizationURL 

func (s *SecurityScheme) GetAuthorizationURL() string

GetAuthorizationURL returns the value of the AuthorizationURL field. Returns empty string if not set.

func (*SecurityScheme) GetDescription 

func (s *SecurityScheme) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*SecurityScheme) GetExtensions 

func (s *SecurityScheme) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*SecurityScheme) GetFlow 

func (s *SecurityScheme) GetFlow() OAuth2Flow

GetFlow returns the value of the Flow field. Returns empty string if not set.

func (*SecurityScheme) GetIn 

func (s *SecurityScheme) GetIn() SecuritySchemeIn

GetIn returns the value of the In field. Returns empty string if not set.

func (*SecurityScheme) GetName 

func (s *SecurityScheme) GetName() string

GetName returns the value of the Name field. Returns empty string if not set.

func (*SecurityScheme) GetScopes 

func (s *SecurityScheme) GetScopes() *sequencedmap.Map[string, string]

GetScopes returns the value of the Scopes field. Returns nil if not set.

func (*SecurityScheme) GetTokenURL 

func (s *SecurityScheme) GetTokenURL() string

GetTokenURL returns the value of the TokenURL field. Returns empty string if not set.

func (*SecurityScheme) GetType 

func (s *SecurityScheme) GetType() SecuritySchemeType

GetType returns the value of the Type field.

func (*SecurityScheme) Validate 

func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the SecurityScheme object against the Swagger Specification.

type SecuritySchemeIn 

type SecuritySchemeIn string

SecuritySchemeIn represents the location of the API key. 

const (
	// SecuritySchemeInQuery represents an API key in the query string.
	SecuritySchemeInQuery SecuritySchemeIn = "query"
	// SecuritySchemeInHeader represents an API key in the header.
	SecuritySchemeInHeader SecuritySchemeIn = "header"
)

type SecuritySchemeType 

type SecuritySchemeType string

SecuritySchemeType represents the type of security scheme. 

const (
	// SecuritySchemeTypeBasic represents basic authentication.
	SecuritySchemeTypeBasic SecuritySchemeType = "basic"
	// SecuritySchemeTypeAPIKey represents API key authentication.
	SecuritySchemeTypeAPIKey SecuritySchemeType = "apiKey"
	// SecuritySchemeTypeOAuth2 represents OAuth2 authentication.
	SecuritySchemeTypeOAuth2 SecuritySchemeType = "oauth2"
)

type Swagger 

type Swagger struct {
	marshaller.Model[core.Swagger]

	// Swagger is the version of the Swagger specification that this document uses.
	Swagger string
	// Info provides metadata about the API.
	Info Info
	// Host is the host (name or ip) serving the API.
	Host *string
	// BasePath is the base path on which the API is served.
	BasePath *string
	// Schemes is the transfer protocol of the API.
	Schemes []string
	// Consumes is a list of MIME types the APIs can consume.
	Consumes []string
	// Produces is a list of MIME types the APIs can produce.
	Produces []string
	// Paths is the available paths and operations for the API.
	Paths *Paths
	// Definitions is an object to hold data types produced and consumed by operations.
	Definitions *sequencedmap.Map[string, *oas3.JSONSchema[oas3.Concrete]]
	// Parameters is an object to hold parameters that can be used across operations.
	Parameters *sequencedmap.Map[string, *Parameter]
	// Responses is an object to hold responses that can be used across operations.
	Responses *sequencedmap.Map[string, *Response]
	// SecurityDefinitions are security scheme definitions that can be used across the specification.
	SecurityDefinitions *sequencedmap.Map[string, *SecurityScheme]
	// Security is a declaration of which security schemes are applied for the API as a whole.
	Security []*SecurityRequirement
	// Tags is a list of tags used by the specification with additional metadata.
	Tags []*Tag
	// ExternalDocs is additional external documentation.
	ExternalDocs *ExternalDocumentation
	// Extensions provides a list of extensions to the Swagger object.
	Extensions *extensions.Extensions
}

Swagger is the root document object for the API specification.

func Unmarshal 

func Unmarshal(ctx context.Context, doc io.Reader, opts ...Option[UnmarshalOptions]) (*Swagger, []error, error)

Unmarshal will unmarshal and validate a Swagger 2.0 document from the provided io.Reader. Validation can be skipped by using swagger.WithSkipValidation() as one of the options when calling this function.

func (*Swagger) GetBasePath 

func (s *Swagger) GetBasePath() string

GetBasePath returns the value of the BasePath field. Returns empty string if not set.

func (*Swagger) GetConsumes 

func (s *Swagger) GetConsumes() []string

GetConsumes returns the value of the Consumes field. Returns nil if not set.

func (*Swagger) GetDefinitions 

func (s *Swagger) GetDefinitions() *sequencedmap.Map[string, *oas3.JSONSchema[oas3.Concrete]]

GetDefinitions returns the value of the Definitions field. Returns nil if not set.

func (*Swagger) GetExtensions 

func (s *Swagger) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Swagger) GetExternalDocs 

func (s *Swagger) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the value of the ExternalDocs field. Returns nil if not set.

func (*Swagger) GetHost 

func (s *Swagger) GetHost() string

GetHost returns the value of the Host field. Returns empty string if not set.

func (*Swagger) GetInfo 

func (s *Swagger) GetInfo() *Info

GetInfo returns the value of the Info field.

func (*Swagger) GetParameters 

func (s *Swagger) GetParameters() *sequencedmap.Map[string, *Parameter]

GetParameters returns the value of the Parameters field. Returns nil if not set.

func (*Swagger) GetPaths 

func (s *Swagger) GetPaths() *Paths

GetPaths returns the value of the Paths field. Returns nil if not set.

func (*Swagger) GetProduces 

func (s *Swagger) GetProduces() []string

GetProduces returns the value of the Produces field. Returns nil if not set.

func (*Swagger) GetResponses 

func (s *Swagger) GetResponses() *sequencedmap.Map[string, *Response]

GetResponses returns the value of the Responses field. Returns nil if not set.

func (*Swagger) GetSchemes 

func (s *Swagger) GetSchemes() []string

GetSchemes returns the value of the Schemes field. Returns nil if not set.

func (*Swagger) GetSecurity 

func (s *Swagger) GetSecurity() []*SecurityRequirement

GetSecurity returns the value of the Security field. Returns nil if not set.

func (*Swagger) GetSecurityDefinitions 

func (s *Swagger) GetSecurityDefinitions() *sequencedmap.Map[string, *SecurityScheme]

GetSecurityDefinitions returns the value of the SecurityDefinitions field. Returns nil if not set.

func (*Swagger) GetSwagger 

func (s *Swagger) GetSwagger() string

GetSwagger returns the value of the Swagger field. Returns empty string if not set.

func (*Swagger) GetTags 

func (s *Swagger) GetTags() []*Tag

GetTags returns the value of the Tags field. Returns nil if not set.

func (*Swagger) Validate 

func (s *Swagger) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Swagger object against the Swagger Specification.

type Tag 

type Tag struct {
	marshaller.Model[core.Tag]

	// Name is the name of the tag.
	Name string
	// Description is a short description for the tag. GFM syntax can be used for rich text representation.
	Description *string
	// ExternalDocs is additional external documentation for this tag.
	ExternalDocs *ExternalDocumentation
	// Extensions provides a list of extensions to the Tag object.
	Extensions *extensions.Extensions
}

Tag allows adding metadata to a single tag that is used by operations.

func (*Tag) GetDescription 

func (t *Tag) GetDescription() string

GetDescription returns the value of the Description field. Returns empty string if not set.

func (*Tag) GetExtensions 

func (t *Tag) GetExtensions() *extensions.Extensions

GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.

func (*Tag) GetExternalDocs 

func (t *Tag) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the value of the ExternalDocs field. Returns nil if not set.

func (*Tag) GetName 

func (t *Tag) GetName() string

GetName returns the value of the Name field. Returns empty string if not set.

func (*Tag) Validate 

func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Tag object against the Swagger Specification.

type UnmarshalOptions 

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

type WalkItem 

type WalkItem struct {
	Match    MatchFunc
	Location Locations
	Swagger  *Swagger
}

WalkItem represents a single item yielded by the Walk iterator.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.