swagger

package
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2025 License: MIT Imports: 23 Imported by: 1

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.