openapi

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: May 18, 2025 License: MIT Imports: 12 Imported by: 1

README

OpenAPI v3.1 Specification

Code Analysis Go Reference codecov GitHub tag (latest SemVer)

The implementation of OpenAPI v3.1 Specification for Go using generics.

Supported Go versions:

  • v1.24
  • v1.23
  • v1.22
  • v1.21

Versions:

  • v0 - Deprecated. The initial version with the full implementation of the v3.1 Specification using generics. See v0 branch.
  • v1 - The current version with the in-place validation of the specification.
    • The minimal version of Go is v1.21.
    • Everything have been moved to root folder. So, the import path is github.com/sv-tools/openapi.
    • Added Validator struct for validation of the specification and the data.
      • Validator.ValidateSpec() method validates the specification.
      • Validator.ValidateData() method validates the data.
      • Validator.ValidateDataAsJSON() method validates the data by converting it into map[string]any type first using json.Marshal and json.Unmarshal. WARNING: the function is slow due to double conversion.
    • Use OpenAPI v3.1.1 by default.

Features

  • The official v3.0 and v3.1 examples are tested. In most cases v3.0 specification can be converted to v3.1 by changing the version's parameter only. 
    @@ -1,4 +1,4 @@
-openapi: "3.0.0"
+openapi: "3.1.0"

NOTE: The descriptions of most structures and their fields are taken from the official documentations.

License

MIT licensed. See the bundled LICENSE file for more details.

Documentation

Index

Constants

View Source 
const (
	// InPath 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.
	//
	// https://spec.openapis.org/oas/v3.1.1#parameter-locations
	InPath = "path"
	// InQuery used for parameters that are appended to the URL.
	// For example, in /items?id=###, the query parameter is id.
	//
	// https://spec.openapis.org/oas/v3.1.1#parameter-locations
	InQuery = "query"
	// InHeader used as custom headers that are expected as part of the request.
	// Note that [RFC7230] states header names are case insensitive.
	//
	// https://spec.openapis.org/oas/v3.1.1#parameter-locations
	InHeader = "header"
	// InCookie used to pass a specific cookie value to the API.
	//
	// https://spec.openapis.org/oas/v3.1.1#parameter-locations
	InCookie = "cookie"

	// StyleMatrix is the parameters defined by [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-3.2.7)
	//
	// Supported types:
	//   - primitive
	//   - array
	//   - object
	//
	// Can be used with `in: path` location.
	StyleMatrix = "matrix"

	// StyleLabel is the parameters defined by [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-3.2.5)
	//
	// Supported types:
	//   - primitive
	//   - array
	//   - object
	//
	// Can be used with `in: path` location.
	StyleLabel = "label"

	// StyleForm is the parameters defined by [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-3.2.8)
	//
	// Supported types:
	//   - primitive
	//   - array
	//   - object
	//
	// Can be used with `in: query` and `in: cookie` locations.
	StyleForm = "form"

	// StyleSimple is the parameters defined by [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-3.2.2)
	// This option replaces collectionFormat with a csv value from OpenAPI 2.0.
	//
	// Supported types:
	//   - array
	//
	// Can be used with `in: path` and `in: header` locations.
	StyleSimple = "simple"

	// StyleSpaceDelimited is space separated array or object values.
	// This option replaces collectionFormat with a ssv value from OpenAPI 2.0.
	//
	// Supported types:
	//   - array
	//   - object
	//
	// Can be used with `in: query` location.
	StyleSpaceDelimited = "spaceDelimited"

	// StylePipeDelimited is pipe separated array or object values.
	// This option replaces collectionFormat with a pipes value from OpenAPI 2.0.
	//
	// Supported types:
	//   - array
	//   - object
	//
	// Can be used with `in: query` location.
	StylePipeDelimited = "pipeDelimited"

	// StyleDeepObject provides a simple way of rendering nested objects using form parameters.
	//
	// Supported types:
	//   - object
	//
	// Can be used with `in: query` location.
	StyleDeepObject = "deepObject"

	ReservedCharacters = ":/?#[]@!$&'()*+,;="
)
View Source 
const (
	TypeApiKey        = "apiKey"
	TypeHTTP          = "http"
	TypeMutualTLS     = "mutualTLS"
	TypeOAuth2        = "oauth2"
	TypeOpenIDConnect = "openIdConnect"
)
View Source 
const (
	Int32Format    = "int32"
	Int64Format    = "int64"
	FloatFormat    = "float"
	DoubleFormat   = "double"
	PasswordFormat = "password"

	// DateTimeFormat is date and time together, for example, 2018-11-13T20:20:39+00:00.
	DateTimeFormat = "date-time"
	// TimeFormat is time, for example, 20:20:39+00:00
	TimeFormat = "time"
	// DateFormat is date, for example, 2018-11-13.
	DateFormat = "date"
	// DurationFormat is a duration as defined by the ISO 8601 ABNF for “duration”.
	// For example, P3D expresses a duration of 3 days.
	//
	// https://datatracker.ietf.org/doc/html/rfc3339#appendix-A
	DurationFormat = "duration"
	// EmailFormat is internet email address, see RFC 5321, section 4.1.2.
	//
	// https://tools.ietf.org/html/rfc5321#section-4.1.2
	EmailFormat = "email"
	// IDNEmailFormat is the internationalized form of an Internet email address, see RFC 6531.
	//
	// https://tools.ietf.org/html/rfc6531
	IDNEmailFormat = "idn-email"
	// HostnameFormat is internet host name, see RFC 1123, section 2.1.
	//
	// https://datatracker.ietf.org/doc/html/rfc1123#section-2.1
	HostnameFormat = "hostname"
	// IDNHostnameFormat is an internationalized Internet host name, see RFC5890, section 2.3.2.3.
	//
	// https://tools.ietf.org/html/rfc6531
	IDNHostnameFormat = "idn-hostname"
	// IPv4Format is IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2673, section 3.2.
	//
	// https://tools.ietf.org/html/rfc2673#section-3.2
	IPv4Format = "ipv4"
	// IPv6Format is IPv6 address, as defined in RFC 2373, section 2.2.
	//
	// https://tools.ietf.org/html/rfc2373#section-2.2
	IPv6Format = "ipv6"
	// UUIDFormat is a Universally Unique Identifier as defined by RFC 4122.
	// Example: 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a
	//
	// RFC 4122
	UUIDFormat = "uuid"
	// URIFormat is a universal resource identifier (URI), according to RFC3986.
	//
	// https://tools.ietf.org/html/rfc3986
	URIFormat = "uri"
	// URIReferenceFormat is a URI Reference (either a URI or a relative-reference), according to RFC3986, section 4.1.
	//
	// https://tools.ietf.org/html/rfc3986#section-4.1
	URIReferenceFormat = "uri-reference"
	// IRIFormat is the internationalized equivalent of a “uri”, according to RFC3987.
	//
	// https://tools.ietf.org/html/rfc3987
	IRIFormat = "iri"
	// IRIReferenceFormat is The internationalized equivalent of a “uri-reference”, according to RFC3987
	//
	// https://tools.ietf.org/html/rfc3987
	IRIReferenceFormat = "iri-reference"
	// URITemplateFormat is a URI Template (of any level) according to RFC6570.
	// If you don’t already know what a URI Template is, you probably don’t need this value.
	//
	// https://tools.ietf.org/html/rfc6570
	URITemplateFormat = "uri-template"
	// JsonPointerFormat is a JSON Pointer, according to RFC6901.
	// There is more discussion on the use of JSON Pointer within JSON Schema in Structuring a complex schema.
	// Note that this should be used only when the entire string contains only JSON Pointer content, e.g. /foo/bar.
	// JSON Pointer URI fragments, e.g. #/foo/bar/ should use "uri-reference".
	//
	// https://tools.ietf.org/html/rfc6901
	JsonPointerFormat = "json-pointer"
	// RelativeJsonPointerFormat is a relative JSON pointer.
	//
	// https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01
	RelativeJsonPointerFormat = "relative-json-pointer"
	// RegexFormat is a regular expression, which should be valid according to the ECMA 262 dialect.
	//
	// https://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf
	RegexFormat = "regex"
)
View Source 
const (

	// StringType is used for strings of text. It may contain Unicode characters.
	//
	// https://json-schema.org/understanding-json-schema/reference/string.html#string
	StringType = "string"
	// NumberType is used for any numeric type, either integers or floating point numbers.
	//
	// https://json-schema.org/understanding-json-schema/reference/numeric.html#number
	NumberType = "number"
	// IntegerType is used for integral numbers.
	// JSON does not have distinct types for integers and floating-point values.
	// Therefore, the presence or absence of a decimal point is not enough to distinguish between integers and non-integers.
	// For example, 1 and 1.0 are two ways to represent the same value in JSON.
	// JSON Schema considers that value an integer no matter which representation was used.
	//
	// https://json-schema.org/understanding-json-schema/reference/numeric.html#integer
	IntegerType = "integer"
	// ObjectType is the mapping type in JSON.
	// They map “keys” to “values”.
	// In JSON, the “keys” must always be strings.
	// Each of these pairs is conventionally referred to as a “property”.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#object
	ObjectType = "object"
	// ArrayType is used for ordered elements.
	// In JSON, each element in an array may be of a different type.
	//
	// https://json-schema.org/understanding-json-schema/reference/array.html#array
	ArrayType = "array"
	// BooleanType matches only two special values: true and false.
	// Note that values that evaluate to true or false, such as 1 and 0, are not accepted by the schema.
	//
	// https://json-schema.org/understanding-json-schema/reference/boolean.html#boolean
	BooleanType = "boolean"
	// NullType has only one acceptable value: null.
	//
	// https://json-schema.org/understanding-json-schema/reference/null.html#null
	NullType = "null"

	SevenBitEncoding        = "7bit"
	EightBitEncoding        = "8bit"
	BinaryEncoding          = "binary"
	QuotedPrintableEncoding = "quoted-printable"
	Base16Encoding          = "base16"
	Base32Encoding          = "base32"
	Base64Encoding          = "base64"
)
View Source 
const (
	// Draft202012 is the default value for the schema field.
	Draft202012 = "https://json-schema.org/draft/2020-12/schema"
)
View Source 
const ExtensionPrefix = "x-"

Variables

View Source 
var (
	ErrRequired          = errors.New("required")
	ErrMutuallyExclusive = errors.New("mutually exclusive")
	ErrUnused            = errors.New("unused")
)
View Source 
var ErrExtensionNameMustStartWithPrefix = errors.New("extension name must start with `" + ExtensionPrefix + "`")
View Source 
var PathNamePattern = regexp.MustCompile(`[^/#?]+$`)
View Source 
var ResponseCodePattern = regexp.MustCompile(`^[1-5](?:\d{2}|XX)$`)

Functions

func ConvertToJSON 

func ConvertToJSON(value any) (any, error)

func GetType 

func GetType(v any) (string, error)

GetType returns the JSON Schema type of the given value.

func NewSpecNotFoundError 

func NewSpecNotFoundError(message string, visitedObjects visitedObjects) error

func NewUnsupportedSpecTypeError 

func NewUnsupportedSpecTypeError(spec any) error

func NewUnsupportedTypeError 

func NewUnsupportedTypeError(v reflect.Kind) error

func NewUnsupportedVersionError 

func NewUnsupportedVersionError(version string) error

Types

type BoolOrSchema 

type BoolOrSchema struct {
	Schema  *RefOrSpec[Schema]
	Allowed bool
}

BoolOrSchema handles Boolean or Schema type.

It MUST be used as a pointer, otherwise the `false` can be omitted by json or yaml encoders in case of `omitempty` tag is set.

func NewBoolOrSchema 

func NewBoolOrSchema(v any) *BoolOrSchema

func (*BoolOrSchema) MarshalJSON 

func (o *BoolOrSchema) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*BoolOrSchema) MarshalYAML 

func (o *BoolOrSchema) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*BoolOrSchema) UnmarshalJSON 

func (o *BoolOrSchema) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*BoolOrSchema) UnmarshalYAML 

func (o *BoolOrSchema) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type Callback 

type Callback struct {
	Paths map[string]*RefOrSpec[Extendable[PathItem]]
}

Callback is a map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. To describe incoming requests from the API provider independent from another API call, use the webhooks field.

https://spec.openapis.org/oas/v3.1.1#callback-object

Example: 

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

func (*Callback) Add 

func (o *Callback) Add(expression string, item *RefOrSpec[Extendable[PathItem]]) *Callback

func (*Callback) MarshalJSON 

func (o *Callback) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Callback) MarshalYAML 

func (o *Callback) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*Callback) UnmarshalJSON 

func (o *Callback) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Callback) UnmarshalYAML 

func (o *Callback) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type CallbackBuilder 

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

func NewCallbackBuilder 

func NewCallbackBuilder() *CallbackBuilder

func (*CallbackBuilder) AddExt 

func (b *CallbackBuilder) AddExt(name string, value any) *CallbackBuilder

func (*CallbackBuilder) AddPathItem 

func (b *CallbackBuilder) AddPathItem(expression string, item *RefOrSpec[Extendable[PathItem]]) *CallbackBuilder

func (*CallbackBuilder) Build 

func (b *CallbackBuilder) Build() *RefOrSpec[Extendable[Callback]]

func (*CallbackBuilder) Extensions 

func (b *CallbackBuilder) Extensions(v map[string]any) *CallbackBuilder

func (*CallbackBuilder) Paths 

func (b *CallbackBuilder) Paths(paths map[string]*RefOrSpec[Extendable[PathItem]]) *CallbackBuilder

type Components 

type Components struct {
	// An object to hold reusable Schema Objects.
	Schemas map[string]*RefOrSpec[Schema] `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	// An object to hold reusable Response Objects.
	Responses map[string]*RefOrSpec[Extendable[Response]] `json:"responses,omitempty" yaml:"responses,omitempty"`
	// An object to hold reusable Parameter Objects.
	Parameters map[string]*RefOrSpec[Extendable[Parameter]] `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// An object to hold reusable Example Objects.
	Examples map[string]*RefOrSpec[Extendable[Example]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	// An object to hold reusable Request Body Objects.
	RequestBodies map[string]*RefOrSpec[Extendable[RequestBody]] `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	// An object to hold reusable Header Objects.
	Headers map[string]*RefOrSpec[Extendable[Header]] `json:"headers,omitempty" yaml:"headers,omitempty"`
	// An object to hold reusable Security Scheme Objects.
	SecuritySchemes map[string]*RefOrSpec[Extendable[SecurityScheme]] `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
	// An object to hold reusable Link Objects.
	Links map[string]*RefOrSpec[Extendable[Link]] `json:"links,omitempty" yaml:"links,omitempty"`
	// An object to hold reusable Callback Objects.
	Callbacks map[string]*RefOrSpec[Extendable[Callback]] `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
	// An object to hold reusable Path Item Object.
	Paths map[string]*RefOrSpec[Extendable[PathItem]] `json:"paths,omitempty" yaml:"paths,omitempty"`
}

Components holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

https://spec.openapis.org/oas/v3.1.1#components-object

Example: 

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

func (*Components) Add 

func (o *Components) Add(name string, v any) *Components

Add adds the given object to the appropriate list based on a type and returns the current object (self|this).

type Contact 

type Contact struct {
	// The identifying name of the contact person/organization.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// The URL pointing to the contact information.
	// This MUST be in the form of a URL.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// The email address of the contact person/organization.
	// This MUST be in the form of an email address.
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
}

Contact information for the exposed API.

https://spec.openapis.org/oas/v3.1.1#contact-object

Example: 

name: API Support
url: https://www.example.com/support
email: support@example.com

type ContactBuilder 

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

func NewContactBuilder 

func NewContactBuilder() *ContactBuilder

func (*ContactBuilder) AddExt 

func (b *ContactBuilder) AddExt(name string, value any) *ContactBuilder

func (*ContactBuilder) Build 

func (b *ContactBuilder) Build() *Extendable[Contact]

func (*ContactBuilder) Email 

func (b *ContactBuilder) Email(v string) *ContactBuilder

func (*ContactBuilder) Extensions 

func (b *ContactBuilder) Extensions(v map[string]any) *ContactBuilder

func (*ContactBuilder) Name 

func (b *ContactBuilder) Name(v string) *ContactBuilder

func (*ContactBuilder) URL 

func (b *ContactBuilder) URL(v string) *ContactBuilder

type Discriminator 

type Discriminator struct {
	// An object to hold mappings between payload values and schema names or references.
	Mapping map[string]string `json:"mapping,omitempty" yaml:"mapping,omitempty"`
	// REQUIRED.
	// The name of the property in the payload that will hold the discriminator value.
	PropertyName string `json:"propertyName" yaml:"propertyName"`
}

Discriminator is used when request bodies or response payloads may be one of a number of different schemas, a discriminator object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. When using the discriminator, inline schemas will not be considered.

https://spec.openapis.org/oas/v3.1.1#discriminator-object

Example: 

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Lizard'
  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'

type DiscriminatorBuilder 

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

func NewDiscriminatorBuilder 

func NewDiscriminatorBuilder() *DiscriminatorBuilder

func (*DiscriminatorBuilder) AddMapping 

func (b *DiscriminatorBuilder) AddMapping(name, value string) *DiscriminatorBuilder

func (*DiscriminatorBuilder) Build 

func (b *DiscriminatorBuilder) Build() *Discriminator

func (*DiscriminatorBuilder) Mapping 

func (b *DiscriminatorBuilder) Mapping(v map[string]string) *DiscriminatorBuilder

func (*DiscriminatorBuilder) PropertyName 

func (b *DiscriminatorBuilder) PropertyName(v string) *DiscriminatorBuilder

type Encoding 

type Encoding struct {
	// The Content-Type for encoding a specific property.
	// Default value depends on the property type:
	//   for object - application/json;
	//   for array – the default is defined based on the inner type;
	//   for all other cases the default is application/octet-stream.
	// The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*),
	// or a comma-separated list of the two types.
	ContentType string `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	// A map allowing additional information to be provided as headers, for example Content-Disposition.
	// Content-Type is described separately and SHALL be ignored in this section.
	// This property SHALL be ignored if the request body media type is not a multipart.
	Headers map[string]*RefOrSpec[Extendable[Header]] `json:"headers,omitempty" yaml:"headers,omitempty"`
	// Describes how a specific property value will be serialized depending on its type.
	// See Parameter Object for details on the style property.
	// The behavior follows the same values as query parameters, including default values.
	// This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data.
	// If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
	Style string `json:"style,omitempty" yaml:"style,omitempty"`
	// When this is true, property values of type array or object generate separate parameters for each value of the array,
	// or key-value-pair of the map.
	// For other types of properties this property has no effect.
	// When style is form, the default value is true.
	// For all other styles, the default value is false.
	// This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data.
	// If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
	Explode bool `json:"explode,omitempty" yaml:"explode,omitempty"`
	// Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986]
	//   :/?#[]@!$&'()*+,;=
	// to be included without percent-encoding.
	// The default value is false.
	// This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data.
	// If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
	AllowReserved bool `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
}

Encoding is definition that applied to a single schema property.

https://spec.openapis.org/oas/v3.1.1#encoding-object

Example: 

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage: {}
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

type EncodingBuilder 

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

func NewEncodingBuilder 

func NewEncodingBuilder() *EncodingBuilder

func (*EncodingBuilder) AddExt 

func (b *EncodingBuilder) AddExt(name string, value any) *EncodingBuilder

func (*EncodingBuilder) AllowReserved 

func (b *EncodingBuilder) AllowReserved(v bool) *EncodingBuilder

func (*EncodingBuilder) Build 

func (b *EncodingBuilder) Build() *Extendable[Encoding]

func (*EncodingBuilder) ContentType 

func (b *EncodingBuilder) ContentType(v string) *EncodingBuilder

func (*EncodingBuilder) Explode 

func (b *EncodingBuilder) Explode(v bool) *EncodingBuilder

func (*EncodingBuilder) Extensions 

func (b *EncodingBuilder) Extensions(v map[string]any) *EncodingBuilder

func (*EncodingBuilder) Header 

func (b *EncodingBuilder) Header(name string, value *RefOrSpec[Extendable[Header]]) *EncodingBuilder

func (*EncodingBuilder) Headers 

func (b *EncodingBuilder) Headers(v map[string]*RefOrSpec[Extendable[Header]]) *EncodingBuilder

func (*EncodingBuilder) Style 

func (b *EncodingBuilder) Style(v string) *EncodingBuilder

type Example 

type Example struct {
	// Short description for the example.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// Long description for the example.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Embedded literal example.
	// The value field and externalValue field are mutually exclusive.
	// To represent examples of media types that cannot naturally represented in JSON or YAML,
	// use a string value to contain the example, escaping where necessary.
	Value any `json:"value,omitempty" yaml:"value,omitempty"`
	// A URI that points to the literal example.
	// This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.
	// The value field and externalValue field are mutually exclusive.
	// See the rules for resolving Relative References.
	ExternalValue string `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`
}

Example is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

https://spec.openapis.org/oas/v3.1.1#example-object

Example: 

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'https://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'https://foo.bar/examples/address-example.txt'

type ExampleBuilder 

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

func NewExampleBuilder 

func NewExampleBuilder() *ExampleBuilder

func (*ExampleBuilder) AddExt 

func (b *ExampleBuilder) AddExt(name string, value any) *ExampleBuilder

func (*ExampleBuilder) Build 

func (b *ExampleBuilder) Build() *RefOrSpec[Extendable[Example]]

func (*ExampleBuilder) Description 

func (b *ExampleBuilder) Description(v string) *ExampleBuilder

func (*ExampleBuilder) Extensions 

func (b *ExampleBuilder) Extensions(v map[string]any) *ExampleBuilder

func (*ExampleBuilder) ExternalValue 

func (b *ExampleBuilder) ExternalValue(v string) *ExampleBuilder

func (*ExampleBuilder) Summary 

func (b *ExampleBuilder) Summary(v string) *ExampleBuilder

func (*ExampleBuilder) Value 

func (b *ExampleBuilder) Value(v any) *ExampleBuilder

type Extendable 

type Extendable[T any] struct {
	Spec       *T             `json:"-" yaml:"-"`
	Extensions map[string]any `json:"-" yaml:"-"`
}

Extendable allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the OpenAPI Initiative. The value can be null, a primitive, an array or an object.

https://spec.openapis.org/oas/v3.1.1#specification-extensions

Example: 

  openapi: 3.1.1
  info:
    title: Sample Pet Store App
    summary: A pet store manager.
    description: This is a sample server for a pet store.
    version: 1.0.1
    x-build-data: 2006-01-02T15:04:05Z07:00
	x-build-commit-id: dac33af14d0d4a5f1c226141042ca7cefc6aeb75

func NewComponents 

func NewComponents() *Extendable[Components]

func NewExtendable 

func NewExtendable[T any](spec *T) *Extendable[T]

NewExtendable creates new Extendable object for given spec

func NewPaths 

func NewPaths() *Extendable[Paths]

func (*Extendable[T]) AddExt 

func (o *Extendable[T]) AddExt(name string, value any) *Extendable[T]

AddExt sets the extension and returns the current object. The `x-` prefix will be added automatically to given name.

func (*Extendable[T]) GetExt 

func (o *Extendable[T]) GetExt(name string) any

GetExt returns the extension value by name. The `x-` prefix will be added automatically to given name.

func (*Extendable[T]) MarshalJSON 

func (o *Extendable[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Extendable[T]) MarshalYAML 

func (o *Extendable[T]) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*Extendable[T]) UnmarshalJSON 

func (o *Extendable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Extendable[T]) UnmarshalYAML 

func (o *Extendable[T]) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type ExternalDocs 

type ExternalDocs struct {
	// A description of the target documentation.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description" yaml:"description"`
	// REQUIRED.
	// The URL for the target documentation.
	// This MUST be in the form of a URL.
	URL string `json:"url" yaml:"url"`
}

ExternalDocs allows referencing an external resource for extended documentation.

https://spec.openapis.org/oas/v3.1.1#external-documentation-object

Example: 

description: Find more info here
url: https://example.com

type ExternalDocsBuilder 

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

func NewExternalDocsBuilder 

func NewExternalDocsBuilder() *ExternalDocsBuilder

func (*ExternalDocsBuilder) AddExt 

func (b *ExternalDocsBuilder) AddExt(name string, value any) *ExternalDocsBuilder

func (*ExternalDocsBuilder) Build 

func (b *ExternalDocsBuilder) Build() *Extendable[ExternalDocs]

func (*ExternalDocsBuilder) Description 

func (b *ExternalDocsBuilder) Description(v string) *ExternalDocsBuilder

func (*ExternalDocsBuilder) Extensions 

func (b *ExternalDocsBuilder) Extensions(v map[string]any) *ExternalDocsBuilder

func (*ExternalDocsBuilder) URL 

func (b *ExternalDocsBuilder) URL(v string) *ExternalDocsBuilder
type Header struct {
	// The schema defining the type used for the header.
	Schema *RefOrSpec[Schema] `json:"schema,omitempty" yaml:"schema,omitempty"`
	// A map containing the representations for the header.
	// The key is the media type and the value describes it.
	// The map MUST only contain one entry.
	Content map[string]*Extendable[MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	// A brief description of the header.
	// This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Describes how the header value will be serialized.
	Style string `json:"style,omitempty" yaml:"style,omitempty"`
	// When this is true, header values of type array or object generate separate headers
	// for each value of the array or key-value pair of the map.
	// For other types of parameters this property has no effect.
	// When style is form, the default value is true.
	// For all other styles, the default value is false.
	Explode bool `json:"explode,omitempty" yaml:"explode,omitempty"`
	// Determines whether this header is mandatory.
	// The property MAY be included and its default value is false.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`
	// Specifies that a header is deprecated and SHOULD be transitioned out of usage.
	// Default value is false.
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

Header Object follows the structure of the Parameter Object with the some changes.

https://spec.openapis.org/oas/v3.1.1#header-object

Example: 

description: The number of allowed requests in the current period
schema:
  type: integer

All fields are copied from Parameter Object as is, except name and in fields.

type HeaderBuilder 

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

func NewHeaderBuilder 

func NewHeaderBuilder() *HeaderBuilder

func (*HeaderBuilder) AddContent 

func (b *HeaderBuilder) AddContent(name string, value *Extendable[MediaType]) *HeaderBuilder

func (*HeaderBuilder) AddExt 

func (b *HeaderBuilder) AddExt(name string, value any) *HeaderBuilder

func (*HeaderBuilder) Build 

func (b *HeaderBuilder) Build() *RefOrSpec[Extendable[Header]]

func (*HeaderBuilder) Content 

func (b *HeaderBuilder) Content(v map[string]*Extendable[MediaType]) *HeaderBuilder

func (*HeaderBuilder) Deprecated 

func (b *HeaderBuilder) Deprecated(v bool) *HeaderBuilder

func (*HeaderBuilder) Description 

func (b *HeaderBuilder) Description(v string) *HeaderBuilder

func (*HeaderBuilder) Explode 

func (b *HeaderBuilder) Explode(v bool) *HeaderBuilder

func (*HeaderBuilder) Extensions 

func (b *HeaderBuilder) Extensions(v map[string]any) *HeaderBuilder

func (*HeaderBuilder) Required 

func (b *HeaderBuilder) Required(v bool) *HeaderBuilder

func (*HeaderBuilder) Schema 

func (b *HeaderBuilder) Schema(v *RefOrSpec[Schema]) *HeaderBuilder

func (*HeaderBuilder) Style 

func (b *HeaderBuilder) Style(v string) *HeaderBuilder

type Info 

type Info struct {
	// REQUIRED.
	// The title of the API.
	Title string `json:"title" yaml:"title"`
	// A short summary of the API.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A description of the API.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A URL to the Terms of Service for the API.
	// This MUST be in the form of a URL.
	TermsOfService string `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
	// The contact information for the exposed API.
	Contact *Extendable[Contact] `json:"contact,omitempty" yaml:"contact,omitempty"`
	// The license information for the exposed API.
	License *Extendable[License] `json:"license,omitempty" yaml:"license,omitempty"`
	// REQUIRED.
	// The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
	Version string `json:"version" yaml:"version"`
}

Info provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

https://spec.openapis.org/oas/v3.1.1#info-object

Example: 

title: Sample Pet Store App
summary: A pet store manager.
description: This is a sample server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

type InfoBuilder 

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

func NewInfoBuilder 

func NewInfoBuilder() *InfoBuilder

func (*InfoBuilder) AddExt 

func (b *InfoBuilder) AddExt(name string, value any) *InfoBuilder

func (*InfoBuilder) Build 

func (b *InfoBuilder) Build() *Extendable[Info]

func (*InfoBuilder) Contact 

func (b *InfoBuilder) Contact(v *Extendable[Contact]) *InfoBuilder

func (*InfoBuilder) Description 

func (b *InfoBuilder) Description(v string) *InfoBuilder

func (*InfoBuilder) Extensions 

func (b *InfoBuilder) Extensions(v map[string]any) *InfoBuilder

func (*InfoBuilder) License 

func (b *InfoBuilder) License(v *Extendable[License]) *InfoBuilder

func (*InfoBuilder) Summary 

func (b *InfoBuilder) Summary(v string) *InfoBuilder

func (*InfoBuilder) TermsOfService 

func (b *InfoBuilder) TermsOfService(v string) *InfoBuilder

func (*InfoBuilder) Title 

func (b *InfoBuilder) Title(v string) *InfoBuilder

func (*InfoBuilder) Version 

func (b *InfoBuilder) Version(v string) *InfoBuilder

type License 

type License struct {
	// REQUIRED.
	// The license name used for the API.
	Name string `json:"name" yaml:"name"`
	// An SPDX license expression for the API.
	// The identifier field is mutually exclusive of the url field.
	Identifier string `json:"identifier,omitempty" yaml:"identifier,omitempty"`
	// A URL to the license used for the API.
	// This MUST be in the form of a URL.
	// The url field is mutually exclusive of the identifier field.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
}

License information for the exposed API.

https://spec.openapis.org/oas/v3.1.1#license-object

Example: 

name: Apache 2.0
identifier: Apache-2.0

type LicenseBuilder 

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

func NewLicenseBuilder 

func NewLicenseBuilder() *LicenseBuilder

func (*LicenseBuilder) AddExt 

func (b *LicenseBuilder) AddExt(name string, value any) *LicenseBuilder

func (*LicenseBuilder) Build 

func (b *LicenseBuilder) Build() *Extendable[License]

func (*LicenseBuilder) Extensions 

func (b *LicenseBuilder) Extensions(v map[string]any) *LicenseBuilder

func (*LicenseBuilder) Identifier 

func (b *LicenseBuilder) Identifier(v string) *LicenseBuilder

func (*LicenseBuilder) Name 

func (b *LicenseBuilder) Name(v string) *LicenseBuilder

func (*LicenseBuilder) URL 

func (b *LicenseBuilder) URL(v string) *LicenseBuilder
type Link struct {
	// A literal value or {expression} to use as a request body when calling the target operation.
	RequestBody any `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	// A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.
	// The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and
	// passed to the linked operation.
	// The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use
	// the same parameter name in different locations (e.g. path.id).
	Parameters map[string]any `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// A server object to be used by the target operation.
	Server *Extendable[Server] `json:"server,omitempty" yaml:"server,omitempty"`
	// A relative or absolute URI reference to an OAS operation.
	// This field is mutually exclusive of the operationId field, and MUST point to an Operation Object.
	// Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition.
	// See the rules for resolving Relative References.
	OperationRef string `json:"operationRef,omitempty" yaml:"operationRef,omitempty"`
	// The name of an existing, resolvable OAS operation, as defined with a unique operationId.
	// This field is mutually exclusive of the operationRef field.
	OperationID string `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	// A description of the link.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Link represents a possible design-time link for a response. The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

https://spec.openapis.org/oas/v3.1.1#link-object

Example: 

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

type LinkBuilder 

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

func NewLinkBuilder 

func NewLinkBuilder() *LinkBuilder

func (*LinkBuilder) AddExt 

func (b *LinkBuilder) AddExt(name string, value any) *LinkBuilder

func (*LinkBuilder) AddParameter 

func (b *LinkBuilder) AddParameter(name string, value any) *LinkBuilder

func (*LinkBuilder) Build 

func (b *LinkBuilder) Build() *RefOrSpec[Extendable[Link]]

func (*LinkBuilder) Description 

func (b *LinkBuilder) Description(v string) *LinkBuilder

func (*LinkBuilder) Extensions 

func (b *LinkBuilder) Extensions(v map[string]any) *LinkBuilder

func (*LinkBuilder) OperationID 

func (b *LinkBuilder) OperationID(v string) *LinkBuilder

func (*LinkBuilder) OperationRef 

func (b *LinkBuilder) OperationRef(v string) *LinkBuilder

func (*LinkBuilder) Parameters 

func (b *LinkBuilder) Parameters(v map[string]any) *LinkBuilder

func (*LinkBuilder) RequestBody 

func (b *LinkBuilder) RequestBody(v any) *LinkBuilder

func (*LinkBuilder) Server 

func (b *LinkBuilder) Server(v *Extendable[Server]) *LinkBuilder

type MediaType 

type MediaType struct {
	// The schema defining the content of the request, response, or parameter.
	Schema *RefOrSpec[Schema] `json:"schema,omitempty" yaml:"schema,omitempty"`
	// Example of the media type. The example object SHOULD be in the correct format as specified by the media type.
	// The example field is mutually exclusive of the examples field.
	// Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema.
	Example any `json:"example,omitempty" yaml:"example,omitempty"`
	// Examples of the parameter’s potential value.
	// Each example SHOULD contain a value in the correct format as specified in the parameter encoding.
	// The examples field is mutually exclusive of the example field.
	// Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
	Examples map[string]*RefOrSpec[Extendable[Example]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	// A map between a property name and its encoding information.
	// The key, being the property name, MUST exist in the schema as a property.
	// The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
	Encoding map[string]*Extendable[Encoding] `json:"encoding,omitempty" yaml:"encoding,omitempty"`
}

MediaType provides schema and examples for the media type identified by its key.

https://spec.openapis.org/oas/v3.1.1#media-type-object

Example: 

application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

type MediaTypeBuilder 

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

func NewMediaTypeBuilder 

func NewMediaTypeBuilder() *MediaTypeBuilder

func (*MediaTypeBuilder) AddEncoding 

func (b *MediaTypeBuilder) AddEncoding(name string, value *Extendable[Encoding]) *MediaTypeBuilder

func (*MediaTypeBuilder) AddExample 

func (b *MediaTypeBuilder) AddExample(name string, value *RefOrSpec[Extendable[Example]]) *MediaTypeBuilder

func (*MediaTypeBuilder) AddExt 

func (b *MediaTypeBuilder) AddExt(name string, value any) *MediaTypeBuilder

func (*MediaTypeBuilder) Build 

func (b *MediaTypeBuilder) Build() *Extendable[MediaType]

func (*MediaTypeBuilder) Encoding 

func (b *MediaTypeBuilder) Encoding(v map[string]*Extendable[Encoding]) *MediaTypeBuilder

func (*MediaTypeBuilder) Example 

func (b *MediaTypeBuilder) Example(v any) *MediaTypeBuilder

func (*MediaTypeBuilder) Examples 

func (b *MediaTypeBuilder) Examples(v map[string]*RefOrSpec[Extendable[Example]]) *MediaTypeBuilder

func (*MediaTypeBuilder) Extensions 

func (b *MediaTypeBuilder) Extensions(v map[string]any) *MediaTypeBuilder

func (*MediaTypeBuilder) Schema 

func (b *MediaTypeBuilder) Schema(v *RefOrSpec[Schema]) *MediaTypeBuilder

type OAuthFlow 

type OAuthFlow struct {
	// REQUIRED.
	// The available scopes for the OAuth2 security scheme.
	// A map between the scope name and a short description for it.
	// The map MAY be empty.
	//
	// Applies To: oauth2
	Scopes map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	// REQUIRED.
	// The authorization URL to be used for this flow.
	// This MUST be in the form of a URL.
	// The OAuth2 standard requires the use of TLS.
	//
	// Applies To:oauth2 ("implicit", "authorizationCode")
	AuthorizationURL string `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	// REQUIRED.
	// The token URL to be used for this flow.
	// This MUST be in the form of a URL.
	// The OAuth2 standard requires the use of TLS.
	//
	// Applies To: oauth2 ("password", "clientCredentials", "authorizationCode")
	TokenURL string `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	// The URL to be used for obtaining refresh tokens.
	// This MUST be in the form of a URL.
	// The OAuth2 standard requires the use of TLS.
	//
	// Applies To: oauth2
	RefreshURL string `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
}

OAuthFlow configuration details for a supported OAuth Flow

https://spec.openapis.org/oas/v3.1.1#oauth-flow-object

Example: 

implicit:
  authorizationUrl: https://example.com/api/oauth/dialog
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets
authorizationCode
  authorizationUrl: https://example.com/api/oauth/dialog
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets

type OAuthFlowBuilder 

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

func NewOAuthFlowBuilder 

func NewOAuthFlowBuilder() *OAuthFlowBuilder

func (*OAuthFlowBuilder) AddExt 

func (b *OAuthFlowBuilder) AddExt(name string, value any) *OAuthFlowBuilder

func (*OAuthFlowBuilder) AddScope 

func (b *OAuthFlowBuilder) AddScope(name, value string) *OAuthFlowBuilder

func (*OAuthFlowBuilder) AuthorizationURL 

func (b *OAuthFlowBuilder) AuthorizationURL(v string) *OAuthFlowBuilder

func (*OAuthFlowBuilder) Build 

func (b *OAuthFlowBuilder) Build() *Extendable[OAuthFlow]

func (*OAuthFlowBuilder) Extensions 

func (b *OAuthFlowBuilder) Extensions(v map[string]any) *OAuthFlowBuilder

func (*OAuthFlowBuilder) RefreshURL 

func (b *OAuthFlowBuilder) RefreshURL(v string) *OAuthFlowBuilder

func (*OAuthFlowBuilder) Scopes 

func (b *OAuthFlowBuilder) Scopes(v map[string]string) *OAuthFlowBuilder

func (*OAuthFlowBuilder) TokenURL 

func (b *OAuthFlowBuilder) TokenURL(v string) *OAuthFlowBuilder

type OAuthFlows 

type OAuthFlows struct {
	// Configuration for the OAuth Implicit flow.
	Implicit *Extendable[OAuthFlow] `json:"implicit,omitempty" yaml:"implicit,omitempty"`
	// Configuration for the OAuth Resource Owner Password flow.
	Password *Extendable[OAuthFlow] `json:"password,omitempty" yaml:"password,omitempty"`
	// Configuration for the OAuth Client Credentials flow.
	// Previously called application in OpenAPI 2.0.
	ClientCredentials *Extendable[OAuthFlow] `json:"clientCredentials,omitempty" yaml:"clientCredentials,omitempty"`
	// Configuration for the OAuth Authorization Code flow.
	// Previously called accessCode in OpenAPI 2.0.
	AuthorizationCode *Extendable[OAuthFlow] `json:"authorizationCode,omitempty" yaml:"authorizationCode,omitempty"`
}

OAuthFlows allows configuration of the supported OAuth Flows.

https://spec.openapis.org/oas/v3.1.1#oauth-flows-object

Example: 

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

type OAuthFlowsBuilder 

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

func NewOAuthFlowsBuilder 

func NewOAuthFlowsBuilder() *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) AddExt 

func (b *OAuthFlowsBuilder) AddExt(name string, value any) *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) AuthorizationCode 

func (b *OAuthFlowsBuilder) AuthorizationCode(v *Extendable[OAuthFlow]) *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) Build 

func (b *OAuthFlowsBuilder) Build() *Extendable[OAuthFlows]

func (*OAuthFlowsBuilder) ClientCredentials 

func (b *OAuthFlowsBuilder) ClientCredentials(v *Extendable[OAuthFlow]) *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) Extensions 

func (b *OAuthFlowsBuilder) Extensions(v map[string]any) *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) Implicit 

func (b *OAuthFlowsBuilder) Implicit(v *Extendable[OAuthFlow]) *OAuthFlowsBuilder

func (*OAuthFlowsBuilder) Password 

func (b *OAuthFlowsBuilder) Password(v *Extendable[OAuthFlow]) *OAuthFlowsBuilder

type OpenAPI 

type OpenAPI struct {
	// An element to hold various schemas for the document.
	Components *Extendable[Components] `json:"components,omitempty" yaml:"components,omitempty"`
	// REQUIRED
	// Provides metadata about the API. The metadata MAY be used by tooling as required.
	Info *Extendable[Info] `json:"info" yaml:"info"`
	// Additional external documentation.
	ExternalDocs *Extendable[ExternalDocs] `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// Holds the relative paths to the individual endpoints and their operations.
	// The path is appended to the URL from the Server Object in order to construct the full URL.
	// The Paths MAY be empty, due to Access Control List (ACL) constraints.
	Paths *Extendable[Paths] `json:"paths,omitempty" yaml:"paths,omitempty"`
	// The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
	// Closely related to the callbacks feature, this section describes requests initiated other than by an API call,
	// for example by an out of band registration.
	// The key name is a unique string to refer to each webhook, while the (optionally referenced) PathItem Object describes
	// a request that may be initiated by the API provider and the expected responses.
	WebHooks Webhooks `json:"webhooks,omitempty" yaml:"webhooks,omitempty"`
	// The default value for the $schema keyword within Schema Objects contained within this OAS document.
	// This MUST be in the form of a URI.
	JsonSchemaDialect string `json:"jsonSchemaDialect,omitempty" yaml:"jsonSchemaDialect,omitempty"`
	// REQUIRED
	// This string MUST be the version number of the OpenAPI Specification that the OpenAPI document uses.
	// The openapi field SHOULD be used by tooling to interpret the OpenAPI document.
	// This is not related to the API info.version string.
	OpenAPI string `json:"openapi" yaml:"openapi"`
	// A declaration of which security mechanisms can be used across the API.
	// The list of values includes alternative security requirement objects that can be used.
	// Only one of the security requirement objects need to be satisfied to authorize a request.
	// Individual operations can override this definition.
	// To make security optional, an empty security requirement ({}) can be included in the array.
	Security []SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`
	// A list of tags used by the document 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.
	Tags []*Extendable[Tag] `json:"tags,omitempty" yaml:"tags,omitempty"`
	// An array of Server Objects, which provide connectivity information to a target server.
	// If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.
	Servers []*Extendable[Server] `json:"servers,omitempty" yaml:"servers,omitempty"`
}

OpenAPI is the root object of the OpenAPI document.

https://spec.openapis.org/oas/v3.1.1#openapi-object

Example: 

openapi: 3.1.1
info:
  title: Minimal OpenAPI example
  version: 1.0.0
paths: { }

type OpenAPIBuilder 

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

func NewOpenAPIBuilder 

func NewOpenAPIBuilder() *OpenAPIBuilder

func (*OpenAPIBuilder) AddComponent 

func (b *OpenAPIBuilder) AddComponent(name string, component any) *OpenAPIBuilder

func (*OpenAPIBuilder) AddExt 

func (b *OpenAPIBuilder) AddExt(name string, value any) *OpenAPIBuilder

func (*OpenAPIBuilder) AddPath 

func (b *OpenAPIBuilder) AddPath(path string, item *RefOrSpec[Extendable[PathItem]]) *OpenAPIBuilder

func (*OpenAPIBuilder) AddSecurity 

func (b *OpenAPIBuilder) AddSecurity(v ...SecurityRequirement) *OpenAPIBuilder

func (*OpenAPIBuilder) AddServers 

func (b *OpenAPIBuilder) AddServers(servers ...*Extendable[Server]) *OpenAPIBuilder

func (*OpenAPIBuilder) AddTags 

func (b *OpenAPIBuilder) AddTags(tags ...*Extendable[Tag]) *OpenAPIBuilder

func (*OpenAPIBuilder) AddWebHook 

func (b *OpenAPIBuilder) AddWebHook(name string, path *RefOrSpec[Extendable[PathItem]]) *OpenAPIBuilder

func (*OpenAPIBuilder) Build 

func (b *OpenAPIBuilder) Build() *Extendable[OpenAPI]

func (*OpenAPIBuilder) Components 

func (b *OpenAPIBuilder) Components(components *Extendable[Components]) *OpenAPIBuilder

func (*OpenAPIBuilder) Extensions 

func (b *OpenAPIBuilder) Extensions(v map[string]any) *OpenAPIBuilder

func (*OpenAPIBuilder) ExternalDocs 

func (b *OpenAPIBuilder) ExternalDocs(externalDocs *Extendable[ExternalDocs]) *OpenAPIBuilder

func (*OpenAPIBuilder) Info 

func (b *OpenAPIBuilder) Info(info *Extendable[Info]) *OpenAPIBuilder

func (*OpenAPIBuilder) JsonSchemaDialect 

func (b *OpenAPIBuilder) JsonSchemaDialect(jsonSchemaDialect string) *OpenAPIBuilder

func (*OpenAPIBuilder) OpenAPI 

func (b *OpenAPIBuilder) OpenAPI(openAPI string) *OpenAPIBuilder

func (*OpenAPIBuilder) Paths 

func (b *OpenAPIBuilder) Paths(paths *Extendable[Paths]) *OpenAPIBuilder

func (*OpenAPIBuilder) Security 

func (b *OpenAPIBuilder) Security(security ...SecurityRequirement) *OpenAPIBuilder

func (*OpenAPIBuilder) Servers 

func (b *OpenAPIBuilder) Servers(servers ...*Extendable[Server]) *OpenAPIBuilder

func (*OpenAPIBuilder) Tags 

func (b *OpenAPIBuilder) Tags(tags ...*Extendable[Tag]) *OpenAPIBuilder

func (*OpenAPIBuilder) WebHooks 

func (b *OpenAPIBuilder) WebHooks(webHooks Webhooks) *OpenAPIBuilder

type Operation 

type Operation struct {
	// The request body applicable for this operation.
	// The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has
	// explicitly defined semantics for request bodies.
	// In other cases where the HTTP spec is vague (such as [GET](section-4.3.1), [HEAD](section-4.3.2) and
	// [DELETE](section-4.3.5)), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
	RequestBody *RefOrSpec[Extendable[RequestBody]] `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	// The list of possible responses as they are returned from executing this operation.
	Responses *Extendable[Responses] `json:"responses,omitempty" yaml:"responses,omitempty"`
	// A map of possible out-of band callbacks related to the parent operation.
	// The key is a unique identifier for the Callback Object.
	// Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.
	Callbacks map[string]*RefOrSpec[Extendable[Callback]] `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
	// Additional external documentation for this operation.
	ExternalDocs *Extendable[ExternalDocs] `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// Unique string used to identify the operation.
	// The id MUST be unique among all operations described in the API.
	// The operationId value is case-sensitive.
	// Tools and libraries MAY use the operationId to uniquely identify an operation, therefore,
	// it is RECOMMENDED to follow common programming naming conventions.
	OperationID string `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	// A short summary of what the operation does.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A verbose explanation of the operation behavior.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A list of parameters that are applicable for this operation.
	// If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
	// The list MUST NOT include duplicated parameters.
	// A unique parameter is defined by a combination of a name and location.
	// The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters.
	Parameters []*RefOrSpec[Extendable[Parameter]] `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// A list of tags for API documentation control.
	// Tags can be used for logical grouping of operations by resources or any other qualifier.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	// A declaration of which security mechanisms can be used for this operation.
	// The list of values includes alternative security requirement objects that can be used.
	// Only one of the security requirement objects need to be satisfied to authorize a request.
	// To make security optional, an empty security requirement ({}) can be included in the array.
	// This definition overrides any declared top-level security.
	// To remove a top-level security declaration, an empty array can be used.
	Security []SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`
	// An alternative server array to service this operation.
	// If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.
	Servers []*Extendable[Server] `json:"servers,omitempty" yaml:"servers,omitempty"`
	// Declares this operation to be deprecated.
	// Consumers SHOULD refrain from usage of the declared operation.
	// Default value is false.
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

Operation Describes a single API operation on a path.

https://spec.openapis.org/oas/v3.1.1#operation-object

Example: 

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       type: object
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

type OperationBuilder 

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

func NewOperationBuilder 

func NewOperationBuilder() *OperationBuilder

func (*OperationBuilder) AddCallback 

func (b *OperationBuilder) AddCallback(name string, value *RefOrSpec[Extendable[Callback]]) *OperationBuilder

func (*OperationBuilder) AddExt 

func (b *OperationBuilder) AddExt(name string, value any) *OperationBuilder

func (*OperationBuilder) AddParameters 

func (b *OperationBuilder) AddParameters(v ...*RefOrSpec[Extendable[Parameter]]) *OperationBuilder

func (*OperationBuilder) AddSecurity 

func (b *OperationBuilder) AddSecurity(v ...SecurityRequirement) *OperationBuilder

func (*OperationBuilder) AddServers 

func (b *OperationBuilder) AddServers(v ...*Extendable[Server]) *OperationBuilder

func (*OperationBuilder) AddTags 

func (b *OperationBuilder) AddTags(v ...string) *OperationBuilder

func (*OperationBuilder) Build 

func (b *OperationBuilder) Build() *Extendable[Operation]

func (*OperationBuilder) Callbacks 

func (b *OperationBuilder) Callbacks(v map[string]*RefOrSpec[Extendable[Callback]]) *OperationBuilder

func (*OperationBuilder) Deprecated 

func (b *OperationBuilder) Deprecated(v bool) *OperationBuilder

func (*OperationBuilder) Description 

func (b *OperationBuilder) Description(v string) *OperationBuilder

func (*OperationBuilder) Extensions 

func (b *OperationBuilder) Extensions(v map[string]any) *OperationBuilder

func (*OperationBuilder) ExternalDocs 

func (b *OperationBuilder) ExternalDocs(v *Extendable[ExternalDocs]) *OperationBuilder

func (*OperationBuilder) OperationID 

func (b *OperationBuilder) OperationID(v string) *OperationBuilder

func (*OperationBuilder) Parameters 

func (b *OperationBuilder) Parameters(v ...*RefOrSpec[Extendable[Parameter]]) *OperationBuilder

func (*OperationBuilder) RequestBody 

func (b *OperationBuilder) RequestBody(v *RefOrSpec[Extendable[RequestBody]]) *OperationBuilder

func (*OperationBuilder) Security 

func (b *OperationBuilder) Security(v ...SecurityRequirement) *OperationBuilder

func (*OperationBuilder) Servers 

func (b *OperationBuilder) Servers(v ...*Extendable[Server]) *OperationBuilder

func (*OperationBuilder) Summary 

func (b *OperationBuilder) Summary(v string) *OperationBuilder

func (*OperationBuilder) Tags 

func (b *OperationBuilder) Tags(v ...string) *OperationBuilder

type Parameter 

type Parameter struct {
	// Example of the parameter’s potential value.
	// The example SHOULD match the specified schema and encoding properties if present.
	// The example field is mutually exclusive of the examples field.
	// Furthermore, if referencing a schema that contains an example, the example value SHALL override the example provided by the schema.
	// To represent examples of media types that cannot naturally be represented in JSON or YAML,
	// a string value can contain the example with escaping where necessary.
	Example any `json:"example,omitempty" yaml:"example,omitempty"`
	// A map containing the representations for the parameter.
	// The key is the media type and the value describes it.
	// The map MUST only contain one entry.
	Content map[string]*Extendable[MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	// Examples of the parameter’s potential value.
	// Each example SHOULD contain a value in the correct format as specified in the parameter encoding.
	// The examples field is mutually exclusive of the example field.
	// Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
	Examples map[string]*RefOrSpec[Extendable[Example]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	// The schema defining the type used for the parameter.
	Schema *RefOrSpec[Schema] `json:"schema,omitempty" yaml:"schema,omitempty"`
	// REQUIRED.
	// The location of the parameter.
	// Possible values are "query", "header", "path" or "cookie".
	In string `json:"in" yaml:"in"`
	// A brief description of the parameter.
	// This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Describes how the parameter value will be serialized depending on the type of the parameter value.
	// Default values (based on value of in):
	//   for query - form;
	//   for path - simple;
	//   for header - simple;
	//   for cookie - form.
	Style string `json:"style,omitempty" yaml:"style,omitempty"`
	// REQUIRED.
	// The name of the parameter.
	// Parameter names are case sensitive.
	// If in is "path", the name field MUST correspond to a template expression occurring within the path field in the Paths Object.
	// See Path Templating for further information.
	// If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.
	// For all other cases, the name corresponds to the parameter name used by the in property.
	Name string `json:"name" yaml:"name"`
	// When this is true, parameter values of type array or object generate separate parameters
	// for each value of the array or key-value pair of the map.
	// For other types of parameters this property has no effect.
	// When style is form, the default value is true.
	// For all other styles, the default value is false.
	Explode bool `json:"explode,omitempty" yaml:"explode,omitempty"`
	// Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986]
	//   :/?#[]@!$&'()*+,;=
	// to be included without percent-encoding.
	// This property only applies to parameters with an in value of query.
	// The default value is false.
	AllowReserved bool `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
	// Sets the ability to pass empty-valued parameters.
	// This is valid only for query parameters and allows sending a parameter with an empty value.
	// Default value is false.
	// If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
	// Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
	AllowEmptyValue bool `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
	// Default value is false.
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	// Determines whether this parameter is mandatory.
	// If the parameter location is "path", this property is REQUIRED and its value MUST be true.
	// Otherwise, the property MAY be included and its default value is false.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`
}

Parameter describes a single operation parameter. A unique parameter is defined by a combination of a name and location.

https://spec.openapis.org/oas/v3.1.1#parameter-object

Example: 

name: pet
description: Pets operations

type ParameterBuilder 

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

func NewParameterBuilder 

func NewParameterBuilder() *ParameterBuilder

func (*ParameterBuilder) AddContent 

func (b *ParameterBuilder) AddContent(name string, value *Extendable[MediaType]) *ParameterBuilder

func (*ParameterBuilder) AddExample 

func (b *ParameterBuilder) AddExample(name string, value *RefOrSpec[Extendable[Example]]) *ParameterBuilder

func (*ParameterBuilder) AddExt 

func (b *ParameterBuilder) AddExt(name string, value any) *ParameterBuilder

func (*ParameterBuilder) AllowEmptyValue 

func (b *ParameterBuilder) AllowEmptyValue(v bool) *ParameterBuilder

func (*ParameterBuilder) AllowReserved 

func (b *ParameterBuilder) AllowReserved(v bool) *ParameterBuilder

func (*ParameterBuilder) Build 

func (b *ParameterBuilder) Build() *RefOrSpec[Extendable[Parameter]]

func (*ParameterBuilder) Content 

func (b *ParameterBuilder) Content(v map[string]*Extendable[MediaType]) *ParameterBuilder

func (*ParameterBuilder) Deprecated 

func (b *ParameterBuilder) Deprecated(v bool) *ParameterBuilder

func (*ParameterBuilder) Description 

func (b *ParameterBuilder) Description(v string) *ParameterBuilder

func (*ParameterBuilder) Example 

func (b *ParameterBuilder) Example(v any) *ParameterBuilder

func (*ParameterBuilder) Examples 

func (b *ParameterBuilder) Examples(v map[string]*RefOrSpec[Extendable[Example]]) *ParameterBuilder

func (*ParameterBuilder) Explode 

func (b *ParameterBuilder) Explode(v bool) *ParameterBuilder

func (*ParameterBuilder) Extensions 

func (b *ParameterBuilder) Extensions(v map[string]any) *ParameterBuilder

func (*ParameterBuilder) In 

func (b *ParameterBuilder) In(v string) *ParameterBuilder

func (*ParameterBuilder) Name 

func (b *ParameterBuilder) Name(v string) *ParameterBuilder

func (*ParameterBuilder) Required 

func (b *ParameterBuilder) Required(v bool) *ParameterBuilder

func (*ParameterBuilder) Schema 

func (b *ParameterBuilder) Schema(v *RefOrSpec[Schema]) *ParameterBuilder

func (*ParameterBuilder) Style 

func (b *ParameterBuilder) Style(v string) *ParameterBuilder

type PathItem 

type PathItem struct {
	// An optional, string summary, intended to apply to all operations in this path.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// An optional, string description, intended to apply to all operations in this path.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A definition of a GET operation on this path.
	Get *Extendable[Operation] `json:"get,omitempty" yaml:"get,omitempty"`
	// A definition of a PUT operation on this path.
	Put *Extendable[Operation] `json:"put,omitempty" yaml:"put,omitempty"`
	// A definition of a POST operation on this path.
	Post *Extendable[Operation] `json:"post,omitempty" yaml:"post,omitempty"`
	// A definition of a DELETE operation on this path.
	Delete *Extendable[Operation] `json:"delete,omitempty" yaml:"delete,omitempty"`
	// A definition of a OPTIONS operation on this path.
	Options *Extendable[Operation] `json:"options,omitempty" yaml:"options,omitempty"`
	// A definition of a HEAD operation on this path.
	Head *Extendable[Operation] `json:"head,omitempty" yaml:"head,omitempty"`
	// A definition of a PATCH operation on this path.
	Patch *Extendable[Operation] `json:"patch,omitempty" yaml:"patch,omitempty"`
	// A definition of a TRACE operation on this path.
	Trace *Extendable[Operation] `json:"trace,omitempty" yaml:"trace,omitempty"`
	// An alternative server array to service all operations in this path.
	Servers []*Extendable[Server] `json:"servers,omitempty" yaml:"servers,omitempty"`
	// A list of parameters that are applicable for all the operations described under this path.
	// These parameters can be overridden at the operation level, but cannot be removed there.
	// The list MUST NOT include duplicated parameters.
	// A unique parameter is defined by a combination of a name and location.
	// The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters.
	Parameters []*RefOrSpec[Extendable[Parameter]] `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

PathItem 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 documentation viewer but they will not know which operations and parameters are available.

https://spec.openapis.org/oas/v3.1.1#path-item-object

Example: 

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string
  style: simple

type PathItemBuilder 

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

func NewPathItemBuilder 

func NewPathItemBuilder() *PathItemBuilder

func (*PathItemBuilder) AddExt 

func (b *PathItemBuilder) AddExt(name string, value any) *PathItemBuilder

func (*PathItemBuilder) AddParameters 

func (b *PathItemBuilder) AddParameters(v ...*RefOrSpec[Extendable[Parameter]]) *PathItemBuilder

func (*PathItemBuilder) AddServers 

func (b *PathItemBuilder) AddServers(v ...*Extendable[Server]) *PathItemBuilder

func (*PathItemBuilder) Build 

func (b *PathItemBuilder) Build() *RefOrSpec[Extendable[PathItem]]

func (*PathItemBuilder) Delete 

func (b *PathItemBuilder) Delete(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Description 

func (b *PathItemBuilder) Description(v string) *PathItemBuilder

func (*PathItemBuilder) Extensions 

func (b *PathItemBuilder) Extensions(v map[string]any) *PathItemBuilder

func (*PathItemBuilder) Get 

func (b *PathItemBuilder) Get(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Head 

func (b *PathItemBuilder) Head(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Options 

func (b *PathItemBuilder) Options(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Parameters 

func (b *PathItemBuilder) Parameters(v ...*RefOrSpec[Extendable[Parameter]]) *PathItemBuilder

func (*PathItemBuilder) Patch 

func (b *PathItemBuilder) Patch(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Post 

func (b *PathItemBuilder) Post(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Put 

func (b *PathItemBuilder) Put(v *Extendable[Operation]) *PathItemBuilder

func (*PathItemBuilder) Servers 

func (b *PathItemBuilder) Servers(v ...*Extendable[Server]) *PathItemBuilder

func (*PathItemBuilder) Summary 

func (b *PathItemBuilder) Summary(v string) *PathItemBuilder

func (*PathItemBuilder) Trace 

func (b *PathItemBuilder) Trace(v *Extendable[Operation]) *PathItemBuilder

type Paths 

type Paths struct {
	// A relative path to an individual endpoint.
	// The field name MUST begin with a forward slash (/).
	// The path is appended (no relative URL resolution) to the expanded URL
	// from the Server Object’s url field in order to construct the full URL.
	// Path templating is allowed.
	// When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts.
	// Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.
	// In case of ambiguous matching, it’s up to the tooling to decide which one to use.
	Paths map[string]*RefOrSpec[Extendable[PathItem]] `json:"-" yaml:"-"`
}

Paths holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to Access Control List (ACL) constraints.

https://spec.openapis.org/oas/v3.1.1#paths-object

Example: 

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

func (*Paths) Add 

func (o *Paths) Add(path string, item *RefOrSpec[Extendable[PathItem]]) *Paths

func (*Paths) MarshalJSON 

func (o *Paths) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Paths) MarshalYAML 

func (o *Paths) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*Paths) UnmarshalJSON 

func (o *Paths) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Paths) UnmarshalYAML 

func (o *Paths) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type Ref 

type Ref struct {
	// REQUIRED.
	// The reference identifier.
	// This MUST be in the form of a URI.
	Ref string `json:"$ref" yaml:"$ref"`
	// A short summary which by default SHOULD override that of the referenced component.
	// If the referenced object-type does not allow a summary field, then this field has no effect.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A description which by default SHOULD override that of the referenced component.
	// CommonMark syntax MAY be used for rich text representation.
	// If the referenced object-type does not allow a description field, then this field has no effect.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Ref is a simple object to allow referencing other components in the OpenAPI document, internally and externally. The $ref string value contains a URI [RFC3986], which identifies the location of the value being referenced. See the rules for resolving Relative References.

https://spec.openapis.org/oas/v3.1.1#reference-object

Example: 

$ref: '#/components/schemas/Pet'

type RefOrSpec 

type RefOrSpec[T any] struct {
	Ref  *Ref `json:"-" yaml:"-"`
	Spec *T   `json:"-" yaml:"-"`
}

RefOrSpec holds either Ref or any OpenAPI spec type.

NOTE: The Ref object takes precedent over Spec if using json or yaml Marshal and Unmarshal functions.

func NewRefOrExtSpec 

func NewRefOrExtSpec[T any](v any) *RefOrSpec[Extendable[T]]

NewRefOrExtSpec creates an object of RefOrSpec[Extendable[any]] type from given Ref or string or any form of Spec.

func NewRefOrSpec 

func NewRefOrSpec[T any](v any) *RefOrSpec[T]

NewRefOrSpec creates an object of RefOrSpec type from given Ref or string or any form of Spec.

func (*RefOrSpec[T]) GetSpec 

func (o *RefOrSpec[T]) GetSpec(c *Extendable[Components]) (*T, error)

GetSpec return a Spec if it is set or loads it from Components in case of Ref or an error

func (*RefOrSpec[T]) MarshalJSON 

func (o *RefOrSpec[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*RefOrSpec[T]) MarshalYAML 

func (o *RefOrSpec[T]) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*RefOrSpec[T]) UnmarshalJSON 

func (o *RefOrSpec[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*RefOrSpec[T]) UnmarshalYAML 

func (o *RefOrSpec[T]) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type RequestBody 

type RequestBody struct {
	// REQUIRED.
	// The content of the request body.
	// The key is a media type or [media type range](appendix-D) and the value describes it.
	// For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
	Content map[string]*Extendable[MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	// A brief description of the request body.
	// This could contain examples of use.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Determines if the request body is required in the request.
	// Defaults to false.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`
}

RequestBody describes a single request body.

https://spec.openapis.org/oas/v3.1.1#request-body-object

Example: 

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'https://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: 'https://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: User example in Plain text
        externalValue: 'https://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: 'https://foo.bar/examples/user-example.whatever'

type RequestBodyBuilder 

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

func NewRequestBodyBuilder 

func NewRequestBodyBuilder() *RequestBodyBuilder

func (*RequestBodyBuilder) AddContent 

func (b *RequestBodyBuilder) AddContent(key string, value *Extendable[MediaType]) *RequestBodyBuilder

func (*RequestBodyBuilder) AddExt 

func (b *RequestBodyBuilder) AddExt(name string, value any) *RequestBodyBuilder

func (*RequestBodyBuilder) Build 

func (b *RequestBodyBuilder) Build() *RefOrSpec[Extendable[RequestBody]]

func (*RequestBodyBuilder) Content 

func (b *RequestBodyBuilder) Content(v map[string]*Extendable[MediaType]) *RequestBodyBuilder

func (*RequestBodyBuilder) Description 

func (b *RequestBodyBuilder) Description(v string) *RequestBodyBuilder

func (*RequestBodyBuilder) Extensions 

func (b *RequestBodyBuilder) Extensions(v map[string]any) *RequestBodyBuilder

func (*RequestBodyBuilder) Required 

func (b *RequestBodyBuilder) Required(v bool) *RequestBodyBuilder

type Response 

type Response struct {
	// Maps a header name to its definition.
	// [RFC7230] states header names are case insensitive.
	// If a response header is defined with the name "Content-Type", it SHALL be ignored.
	Headers map[string]*RefOrSpec[Extendable[Header]] `json:"headers,omitempty" yaml:"headers,omitempty"`
	// A map containing descriptions of potential response payloads.
	// The key is a media type or [media type range](appendix-D) and the value describes it.
	// For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
	Content map[string]*Extendable[MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	// A map of operations links that can be followed from the response.
	// The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.
	Links map[string]*RefOrSpec[Extendable[Link]] `json:"links,omitempty" yaml:"links,omitempty"`
	// REQUIRED.
	// A description of the response.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Response describes a single response from an API Operation, including design-time, static links to operations based on the response.

https://spec.openapis.org/oas/v3.1.1#response-object

Example: 

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

type ResponseBuilder 

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

func NewResponseBuilder 

func NewResponseBuilder() *ResponseBuilder

func (*ResponseBuilder) AddContent 

func (b *ResponseBuilder) AddContent(key string, value *Extendable[MediaType]) *ResponseBuilder

func (*ResponseBuilder) AddExt 

func (b *ResponseBuilder) AddExt(name string, value any) *ResponseBuilder

func (*ResponseBuilder) AddHeader 

func (b *ResponseBuilder) AddHeader(key string, value *RefOrSpec[Extendable[Header]]) *ResponseBuilder
func (b *ResponseBuilder) AddLink(key string, value *RefOrSpec[Extendable[Link]]) *ResponseBuilder

func (*ResponseBuilder) Build 

func (b *ResponseBuilder) Build() *RefOrSpec[Extendable[Response]]

func (*ResponseBuilder) Content 

func (b *ResponseBuilder) Content(v map[string]*Extendable[MediaType]) *ResponseBuilder

func (*ResponseBuilder) Description 

func (b *ResponseBuilder) Description(v string) *ResponseBuilder

func (*ResponseBuilder) Extensions 

func (b *ResponseBuilder) Extensions(v map[string]any) *ResponseBuilder

func (*ResponseBuilder) Headers 

func (b *ResponseBuilder) Headers(v map[string]*RefOrSpec[Extendable[Header]]) *ResponseBuilder
func (b *ResponseBuilder) Links(v map[string]*RefOrSpec[Extendable[Link]]) *ResponseBuilder

type Responses 

type Responses struct {
	// The documentation of responses other than the ones declared for specific HTTP response codes.
	// Use this field to cover undeclared responses.
	Default *RefOrSpec[Extendable[Response]] `json:"default,omitempty" yaml:"default,omitempty"`
	// Any HTTP status code can be used as the property name, but only one property per code,
	// to describe the expected response for that HTTP status code.
	// This field MUST be enclosed in quotation marks (for example, “200”) for compatibility between JSON and YAML.
	// To define a range of response codes, this field MAY contain the uppercase wildcard character X.
	// For example, 2XX represents all response codes between [200-299].
	// Only the following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX.
	// If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
	Response map[string]*RefOrSpec[Extendable[Response]] `json:"-" yaml:"-"`
}

Responses is a container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The default MAY be used as a default response object for all HTTP codes that are not covered individually by the Responses Object. The Responses Object MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call.

https://spec.openapis.org/oas/v3.1.1#responses-object

Example: 

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

func (*Responses) MarshalJSON 

func (o *Responses) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Responses) MarshalYAML 

func (o *Responses) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*Responses) UnmarshalJSON 

func (o *Responses) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Responses) UnmarshalYAML 

func (o *Responses) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type ResponsesBuilder 

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

func NewResponsesBuilder 

func NewResponsesBuilder() *ResponsesBuilder

func (*ResponsesBuilder) AddExt 

func (b *ResponsesBuilder) AddExt(name string, value any) *ResponsesBuilder

func (*ResponsesBuilder) AddResponse 

func (b *ResponsesBuilder) AddResponse(key string, value *RefOrSpec[Extendable[Response]]) *ResponsesBuilder

func (*ResponsesBuilder) Build 

func (b *ResponsesBuilder) Build() *RefOrSpec[Extendable[Responses]]

func (*ResponsesBuilder) Default 

func (b *ResponsesBuilder) Default(v *RefOrSpec[Extendable[Response]]) *ResponsesBuilder

func (*ResponsesBuilder) Extensions 

func (b *ResponsesBuilder) Extensions(v map[string]any) *ResponsesBuilder

func (*ResponsesBuilder) Response 

func (b *ResponsesBuilder) Response(v map[string]*RefOrSpec[Extendable[Response]]) *ResponsesBuilder

type Schema 

type Schema struct {

	// The $schema keyword is used to declare which dialect of JSON Schema the schema was written for.
	// The value of the $schema keyword is also the identifier for a schema that can be used to verify
	// that the schema is valid according to the dialect $schema identifies.
	// A schema that describes another schema is called a "meta-schema".
	// $schema applies to the entire document and must be at the root level.
	// It does not apply to externally referenced ($ref, $dynamicRef) documents.
	// Those schemas need to declare their own $schema.
	// If $schema is not used, an implementation might allow you to specify a value externally or
	// it might make assumptions about which specification version should be used to evaluate the schema.
	// It's recommended that all JSON Schemas have a $schema keyword to communicate to readers and
	// tooling which specification version is intended.
	//
	// https://json-schema.org/understanding-json-schema/reference/schema#schema
	Schema string `json:"$schema,omitempty" yaml:"$schema,omitempty"`
	// The value of $id is a URI-reference without a fragment that resolves against the retrieval-uri.
	// The resulting URI is the base URI for the schema.
	//
	// https://json-schema.org/understanding-json-schema/structuring#id
	ID string `json:"$id,omitempty" yaml:"$id,omitempty"`
	// https://json-schema.org/understanding-json-schema/structuring#dollardefs
	Defs          map[string]*RefOrSpec[Schema] `json:"$defs,omitempty"          yaml:"$defs,omitempty"`
	DynamicRef    string                        `json:"$dynamicRef,omitempty"    yaml:"$dynamicRef,omitempty"`
	Vocabulary    map[string]bool               `json:"$vocabulary,omitempty"    yaml:"$vocabulary,omitempty"`
	DynamicAnchor string                        `json:"$dynamicAnchor,omitempty" yaml:"dynamicAnchor,omitempty"`
	// https://json-schema.org/understanding-json-schema/reference/type#type-specific-keywords
	Type *SingleOrArray[string] `json:"type,omitempty" yaml:"type,omitempty"`

	// The default keyword specifies a default value.
	// This value is not used to fill in missing values during the validation process.
	// Non-validation tools such as documentation generators or form generators may use this value
	// to give hints to users about how to use a value.
	// However, default is typically used to express that if a value is missing,
	// then the value is semantically the same as if the value was present with the default value.
	// The value of default should validate against the schema in which it resides, but that isn't required.
	Default any `json:"default,omitempty" yaml:"default,omitempty"`
	// The title keyword preferably be short.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// The description keyword provides a more lengthy explanation about the purpose of the data described by the schema.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// The const keyword is used to restrict a value to a single value.
	//
	// https://json-schema.org/understanding-json-schema/reference/const
	Const string `json:"const,omitempty" yaml:"const,omitempty"`
	// The $comment keyword is strictly intended for adding comments to a schema.
	// Its value must always be a string.
	// Unlike the annotations title, description, and examples, JSON schema implementations aren’t allowed
	// to attach any meaning or behavior to it whatsoever, and may even strip them at any time.
	// Therefore, they are useful for leaving notes to future editors of a JSON schema,
	// but should not be used to communicate to users of the schema.
	//
	// https://json-schema.org/understanding-json-schema/reference/generic.html#comments
	Comment string `json:"$comment,omitempty" yaml:"$comment,omitempty"`
	// The enum keyword is used to restrict a value to a fixed set of values.
	// It must be an array with at least one element, where each element is unique.
	//
	// https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values
	Enum []any `json:"enum,omitempty" yaml:"enum,omitempty"`
	// The examples keyword is a place to provide an array of examples that validate against the schema.
	// This isn't used for validation, but may help with explaining the effect and purpose of the schema to a reader.
	// Each entry should validate against the schema in which it resides, but that isn't strictly required.
	// There is no need to duplicate the default value in the examples array,
	// since default will be treated as another example.
	Examples []any `json:"examples,omitempty" yaml:"examples,omitempty"`
	// The readOnly indicates that a value should not be modified.
	// It could be used to indicate that a PUT request that changes a value would result in a 400 Bad Request response.
	ReadOnly bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	// The writeOnly indicates that a value may be set, but will remain hidden.
	// In could be used to indicate you can set a value with a PUT request,
	// but it would not be included when retrieving that record with a GET request.
	WriteOnly bool `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
	// The deprecated keyword is a boolean that indicates that the instance value the keyword applies to
	// should not be used and may be removed in the future.
	Deprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`

	// https://json-schema.org/understanding-json-schema/reference/non_json_data#contentschema
	ContentSchema *RefOrSpec[Schema] `json:"contentSchema,omitempty" yaml:"contentSchema,omitempty"`
	// The contentMediaType keyword specifies the MIME type of the contents of a string, as described in RFC 2046.
	// There is a list of MIME types officially registered by the IANA, but the set of types supported will be
	// application and operating system dependent.
	//
	// https://json-schema.org/understanding-json-schema/reference/non_json_data#contentmediatype
	ContentMediaType string `json:"contentMediaType,omitempty" yaml:"contentMediaType,omitempty"`
	// The contentEncoding keyword specifies the encoding used to store the contents, as specified in RFC 2054, part 6.1 and RFC 4648.
	//
	// https://json-schema.org/understanding-json-schema/reference/non_json_data#contentencoding
	ContentEncoding string `json:"contentEncoding,omitempty" yaml:"contentEncoding,omitempty"`

	// The not keyword declares that an instance validates if it doesn’t validate against the given subschema.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html#not
	Not *RefOrSpec[Schema] `json:"not,omitempty" yaml:"not,omitempty"`
	// To validate against allOf, the given data must be valid against all of the given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html#allof
	AllOf []*RefOrSpec[Schema] `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	// To validate against anyOf, the given data must be valid against any (one or more) of the given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html#anyof
	AnyOf []*RefOrSpec[Schema] `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	// To validate against oneOf, the given data must be valid against exactly one of the given subschemas.
	//
	// https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
	OneOf []*RefOrSpec[Schema] `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`

	// The dependentRequired keyword conditionally requires that certain properties must be present if
	// a given property is present in an object.
	// For example, suppose we have a schema representing a customer.
	// If you have their credit card number, you also want to ensure you have a billing address.
	// If you don’t have their credit card number, a billing address would not be required.
	// We represent this dependency of one property on another using the dependentRequired keyword.
	// The value of the dependentRequired keyword is an object.
	// Each entry in the object maps from the name of a property, p, to an array of strings listing properties that
	// are required if p is present.
	//
	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#dependentrequired
	DependentRequired map[string][]string `json:"dependentRequired,omitempty" yaml:"dependentRequired,omitempty"`
	// The dependentSchemas keyword conditionally applies a subschema when a given property is present.
	// This schema is applied in the same way allOf applies schemas.
	// Nothing is merged or extended.
	// Both schemas apply independently.
	//
	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#dependentschemas
	DependentSchemas map[string]*RefOrSpec[Schema] `json:"dependentSchemas,omitempty" yaml:"dependentSchemas,omitempty"`

	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#if-then-else
	If   *RefOrSpec[Schema] `json:"if,omitempty"   yaml:"if,omitempty"`
	Then *RefOrSpec[Schema] `json:"then,omitempty" yaml:"then,omitempty"`
	Else *RefOrSpec[Schema] `json:"else,omitempty" yaml:"else,omitempty"`

	// MultipleOf restricts the numbers to a multiple of a given number, using the multipleOf keyword.
	// It may be set to any positive number.
	//
	// https://json-schema.org/understanding-json-schema/reference/numeric.html#multiples
	MultipleOf *int `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	// x ≥ minimum
	Minimum *int `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	// x > exclusiveMinimum
	ExclusiveMinimum *int `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	// x ≤ maximum
	Maximum *int `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	// x < exclusiveMaximum
	ExclusiveMaximum *int `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`

	MinLength *int   `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MaxLength *int   `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	Pattern   string `json:"pattern,omitempty"   yaml:"pattern,omitempty"`
	Format    string `json:"format,omitempty"    yaml:"format,omitempty"`

	// List validation is useful for arrays of arbitrary length where each item matches the same schema.
	// For this kind of array, set the items keyword to a single schema that will be used to validate all of the items in the array.
	//
	// https://json-schema.org/understanding-json-schema/reference/array#items
	Items *BoolOrSchema `json:"items,omitempty" yaml:"items,omitempty"`
	// https://json-schema.org/understanding-json-schema/reference/array#length
	MaxItems *int `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	// The unevaluatedItems keyword is similar to unevaluatedProperties, but for items.
	//
	// https://json-schema.org/understanding-json-schema/reference/array#unevaluateditems
	UnevaluatedItems *BoolOrSchema `json:"unevaluatedItems,omitempty" yaml:"unevaluatedItems,omitempty"`
	// While the items schema must be valid for every item in the array, the contains schema only needs
	// to validate against one or more items in the array.
	//
	// https://json-schema.org/understanding-json-schema/reference/array.html#contains
	Contains    *RefOrSpec[Schema] `json:"contains,omitempty"    yaml:"contains,omitempty"`
	MinContains *int               `json:"minContains,omitempty" yaml:"minContains,omitempty"`
	MaxContains *int               `json:"maxContains,omitempty" yaml:"maxContains,omitempty"`
	// https://json-schema.org/understanding-json-schema/reference/array.html#length
	MinItems *int `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	// A schema can ensure that each of the items in an array is unique.
	// Simply set the uniqueItems keyword to true.
	//
	// https://json-schema.org/understanding-json-schema/reference/array.html#uniqueness
	UniqueItems *bool `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	// The prefixItems is an array, where each item is a schema that corresponds to each index of the document’s array.
	// That is, an array where the first element validates the first element of the input array,
	// the second element validates the second element of the input array, etc.
	//
	// https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation
	PrefixItems []*RefOrSpec[Schema] `json:"prefixItems,omitempty" yaml:"prefixItems,omitempty"`

	// The properties (key-value pairs) on an object are defined using the properties keyword.
	// The value of properties is an object, where each key is the name of a property and each value is
	// a schema used to validate that property.
	// Any property that doesn't match any of the property names in the properties keyword is ignored by this keyword.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#properties
	Properties map[string]*RefOrSpec[Schema] `json:"properties,omitempty" yaml:"properties,omitempty"`
	// Sometimes you want to say that, given a particular kind of property name, the value should match a particular schema.
	// That’s where patternProperties comes in: it maps regular expressions to schemas.
	// If a property name matches the given regular expression, the property value must validate against the corresponding schema.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#pattern-properties
	PatternProperties map[string]*RefOrSpec[Schema] `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`
	// The additionalProperties keyword is used to control the handling of extra stuff, that is,
	// properties whose names are not listed in the properties keyword or match any of the regular expressions
	// in the patternProperties keyword.
	// By default any additional properties are allowed.
	//
	// The value of the additionalProperties keyword is a schema that will be used to validate any properties in the instance
	// that are not matched by properties or patternProperties.
	// Setting the additionalProperties schema to false means no additional properties will be allowed.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#additional-properties
	AdditionalProperties *BoolOrSchema `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	// The unevaluatedProperties keyword is similar to additionalProperties except that it can recognize properties declared in subschemas.
	// So, the example from the previous section can be rewritten without the need to redeclare properties.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#unevaluated-properties
	UnevaluatedProperties *BoolOrSchema `json:"unevaluatedProperties,omitempty" yaml:"unevaluatedProperties,omitempty"`
	// The names of properties can be validated against a schema, irrespective of their values.
	// This can be useful if you don’t want to enforce specific properties, but you want to make sure that
	// the names of those properties follow a specific convention.
	// You might, for example, want to enforce that all names are valid ASCII tokens so they can be used
	// as attributes in a particular programming language.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#property-names
	PropertyNames *RefOrSpec[Schema] `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`
	// The min number of properties on an object.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#size
	MinProperties *int `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	// The max number of properties on an object.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#size
	MaxProperties *int `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	// The required keyword takes an array of zero or more strings.
	// Each of these strings must be unique.
	//
	// https://json-schema.org/understanding-json-schema/reference/object.html#required-properties
	Required []string `json:"required,omitempty" yaml:"required,omitempty"`

	// Adds support for polymorphism.
	// The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description.
	// See Composition and Inheritance for more details.
	Discriminator *Discriminator `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
	// Additional external documentation for this tag.
	// xml
	XML *Extendable[XML] `json:"xml,omitempty" yaml:"xml,omitempty"`
	// Additional external documentation for this schema.
	ExternalDocs *Extendable[ExternalDocs] `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A free-form property to include an example of an instance for this schema.
	// To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to
	// contain the example with escaping where necessary.
	//
	// Deprecated: The example property has been deprecated in favor of the JSON Schema examples keyword.
	// Use of example is discouraged, and later versions of this specification may remove it.
	Example any `json:"example,omitempty" yaml:"example,omitempty"`

	Extensions map[string]any `json:"-" yaml:"-"`

	// GoPackage is a custom field to store the Go package of the schema.
	GoPackage string `json:"x-go-package,omitempty" yaml:"x-go-package,omitempty"`
	// GoType is a custom field to store the Go type of the schema.
	GoType string `json:"x-go-type,omitempty" yaml:"x-go-type,omitempty"`
}

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12. For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.

https://spec.openapis.org/oas/v3.1.1#schema-object https://json-schema.org/understanding-json-schema/index.html

func (*Schema) AddExt 

func (o *Schema) AddExt(name string, value any) *Schema

AddExt sets the extension and returns the current object (self|this). Schema does not require special `x-` prefix. The extension will be ignored if the name overlaps with a struct field during marshaling to JSON or YAML.

func (*Schema) GetExt 

func (o *Schema) GetExt(name string) any

func (*Schema) MarshalJSON 

func (o *Schema) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Schema) MarshalYAML 

func (o *Schema) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*Schema) UnmarshalJSON 

func (o *Schema) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Schema) UnmarshalYAML 

func (o *Schema) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type SchemaBulder 

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

func NewSchemaBuilder 

func NewSchemaBuilder() *SchemaBulder

func (*SchemaBulder) AddAllOf 

func (b *SchemaBulder) AddAllOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddAnyOf 

func (b *SchemaBulder) AddAnyOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddDef 

func (b *SchemaBulder) AddDef(name string, value *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddDependentRequired 

func (b *SchemaBulder) AddDependentRequired(name string, value ...string) *SchemaBulder

func (*SchemaBulder) AddDependentSchema 

func (b *SchemaBulder) AddDependentSchema(name string, value *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddEnum 

func (b *SchemaBulder) AddEnum(v ...any) *SchemaBulder

func (*SchemaBulder) AddExamples 

func (b *SchemaBulder) AddExamples(v ...any) *SchemaBulder

func (*SchemaBulder) AddExt 

func (b *SchemaBulder) AddExt(name string, value any) *SchemaBulder

func (*SchemaBulder) AddOneOf 

func (b *SchemaBulder) AddOneOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddPatternProperty 

func (b *SchemaBulder) AddPatternProperty(name string, value *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddPrefixItems 

func (b *SchemaBulder) AddPrefixItems(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddProperty 

func (b *SchemaBulder) AddProperty(name string, value *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AddRequired 

func (b *SchemaBulder) AddRequired(v ...string) *SchemaBulder

func (*SchemaBulder) AddType 

func (b *SchemaBulder) AddType(v ...string) *SchemaBulder

func (*SchemaBulder) AddVocabulary 

func (b *SchemaBulder) AddVocabulary(name string, value bool) *SchemaBulder

func (*SchemaBulder) AdditionalProperties 

func (b *SchemaBulder) AdditionalProperties(v *BoolOrSchema) *SchemaBulder

func (*SchemaBulder) AllOf 

func (b *SchemaBulder) AllOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) AnyOf 

func (b *SchemaBulder) AnyOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Build 

func (b *SchemaBulder) Build() *RefOrSpec[Schema]

func (*SchemaBulder) Comment 

func (b *SchemaBulder) Comment(v string) *SchemaBulder

func (*SchemaBulder) Const 

func (b *SchemaBulder) Const(v string) *SchemaBulder

func (*SchemaBulder) Contains 

func (b *SchemaBulder) Contains(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) ContentEncoding 

func (b *SchemaBulder) ContentEncoding(v string) *SchemaBulder

func (*SchemaBulder) ContentMediaType 

func (b *SchemaBulder) ContentMediaType(v string) *SchemaBulder

func (*SchemaBulder) ContentSchema 

func (b *SchemaBulder) ContentSchema(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Default 

func (b *SchemaBulder) Default(v any) *SchemaBulder

func (*SchemaBulder) Defs 

func (b *SchemaBulder) Defs(v map[string]*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) DependentRequired 

func (b *SchemaBulder) DependentRequired(v map[string][]string) *SchemaBulder

func (*SchemaBulder) DependentSchemas 

func (b *SchemaBulder) DependentSchemas(v map[string]*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Deprecated 

func (b *SchemaBulder) Deprecated(v bool) *SchemaBulder

func (*SchemaBulder) Description 

func (b *SchemaBulder) Description(v string) *SchemaBulder

func (*SchemaBulder) Discriminator 

func (b *SchemaBulder) Discriminator(v *Discriminator) *SchemaBulder

func (*SchemaBulder) DynamicAnchor 

func (b *SchemaBulder) DynamicAnchor(v string) *SchemaBulder

func (*SchemaBulder) DynamicRef 

func (b *SchemaBulder) DynamicRef(v string) *SchemaBulder

func (*SchemaBulder) Else 

func (b *SchemaBulder) Else(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Enum 

func (b *SchemaBulder) Enum(v ...any) *SchemaBulder

func (*SchemaBulder) Example 

func (b *SchemaBulder) Example(v any) *SchemaBulder

func (*SchemaBulder) Examples 

func (b *SchemaBulder) Examples(v ...any) *SchemaBulder

func (*SchemaBulder) ExclusiveMaximum 

func (b *SchemaBulder) ExclusiveMaximum(v int) *SchemaBulder

func (*SchemaBulder) ExclusiveMinimum 

func (b *SchemaBulder) ExclusiveMinimum(v int) *SchemaBulder

func (*SchemaBulder) Extensions 

func (b *SchemaBulder) Extensions(v map[string]any) *SchemaBulder

func (*SchemaBulder) ExternalDocs 

func (b *SchemaBulder) ExternalDocs(v *Extendable[ExternalDocs]) *SchemaBulder

func (*SchemaBulder) Format 

func (b *SchemaBulder) Format(v string) *SchemaBulder

func (*SchemaBulder) GoPackage 

func (b *SchemaBulder) GoPackage(v string) *SchemaBulder

func (*SchemaBulder) GoType 

func (b *SchemaBulder) GoType(v string) *SchemaBulder

func (*SchemaBulder) ID 

func (b *SchemaBulder) ID(v string) *SchemaBulder

func (*SchemaBulder) If 

func (b *SchemaBulder) If(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) IsRef 

func (b *SchemaBulder) IsRef() bool

func (*SchemaBulder) Items 

func (b *SchemaBulder) Items(v *BoolOrSchema) *SchemaBulder

func (*SchemaBulder) MaxContains 

func (b *SchemaBulder) MaxContains(v int) *SchemaBulder

func (*SchemaBulder) MaxItems 

func (b *SchemaBulder) MaxItems(v int) *SchemaBulder

func (*SchemaBulder) MaxLength 

func (b *SchemaBulder) MaxLength(v int) *SchemaBulder

func (*SchemaBulder) MaxProperties 

func (b *SchemaBulder) MaxProperties(v int) *SchemaBulder

func (*SchemaBulder) Maximum 

func (b *SchemaBulder) Maximum(v int) *SchemaBulder

func (*SchemaBulder) MinContains 

func (b *SchemaBulder) MinContains(v int) *SchemaBulder

func (*SchemaBulder) MinItems 

func (b *SchemaBulder) MinItems(v int) *SchemaBulder

func (*SchemaBulder) MinLength 

func (b *SchemaBulder) MinLength(v int) *SchemaBulder

func (*SchemaBulder) MinProperties 

func (b *SchemaBulder) MinProperties(v int) *SchemaBulder

func (*SchemaBulder) Minimum 

func (b *SchemaBulder) Minimum(v int) *SchemaBulder

func (*SchemaBulder) MultipleOf 

func (b *SchemaBulder) MultipleOf(v int) *SchemaBulder

func (*SchemaBulder) Not 

func (b *SchemaBulder) Not(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) OneOf 

func (b *SchemaBulder) OneOf(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Pattern 

func (b *SchemaBulder) Pattern(v string) *SchemaBulder

func (*SchemaBulder) PatternProperties 

func (b *SchemaBulder) PatternProperties(v map[string]*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) PrefixItems 

func (b *SchemaBulder) PrefixItems(v ...*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Properties 

func (b *SchemaBulder) Properties(v map[string]*RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) PropertyNames 

func (b *SchemaBulder) PropertyNames(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) ReadOnly 

func (b *SchemaBulder) ReadOnly(v bool) *SchemaBulder

func (*SchemaBulder) Ref 

func (b *SchemaBulder) Ref(v string) *SchemaBulder

func (*SchemaBulder) Required 

func (b *SchemaBulder) Required(v ...string) *SchemaBulder

func (*SchemaBulder) Schema 

func (b *SchemaBulder) Schema(v string) *SchemaBulder

func (*SchemaBulder) Then 

func (b *SchemaBulder) Then(v *RefOrSpec[Schema]) *SchemaBulder

func (*SchemaBulder) Title 

func (b *SchemaBulder) Title(v string) *SchemaBulder

func (*SchemaBulder) Type 

func (b *SchemaBulder) Type(v ...string) *SchemaBulder

func (*SchemaBulder) UnevaluatedItems 

func (b *SchemaBulder) UnevaluatedItems(v *BoolOrSchema) *SchemaBulder

func (*SchemaBulder) UnevaluatedProperties 

func (b *SchemaBulder) UnevaluatedProperties(v *BoolOrSchema) *SchemaBulder

func (*SchemaBulder) UniqueItems 

func (b *SchemaBulder) UniqueItems(v bool) *SchemaBulder

func (*SchemaBulder) Vocabulary 

func (b *SchemaBulder) Vocabulary(v map[string]bool) *SchemaBulder

func (*SchemaBulder) WriteOnly 

func (b *SchemaBulder) WriteOnly(v bool) *SchemaBulder

func (*SchemaBulder) XML 

func (b *SchemaBulder) XML(v *Extendable[XML]) *SchemaBulder

type SecurityRequirement 

type SecurityRequirement map[string][]string

SecurityRequirement is the lists of the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object, only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.

https://spec.openapis.org/oas/v3.1.1#security-requirement-object

Example: 

api_key: []

type SecurityRequirementBuilder 

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

func NewSecurityRequirementBuilder 

func NewSecurityRequirementBuilder() *SecurityRequirementBuilder

func (*SecurityRequirementBuilder) Add 

func (b *SecurityRequirementBuilder) Add(name string, scopes ...string) *SecurityRequirementBuilder

func (*SecurityRequirementBuilder) Build 

func (b *SecurityRequirementBuilder) Build() *SecurityRequirement

type SecurityScheme 

type SecurityScheme struct {
	// REQUIRED.
	// The type of the security scheme.
	// Valid values are "apiKey", "http", "mutualTLS", "oauth2", "openIdConnect".
	//
	// Applies To: any
	Type string `json:"type" yaml:"type"`
	// A description for security scheme.
	// CommonMark syntax MAY be used for rich text representation.
	//
	// Applies To: any
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// REQUIRED.
	// The name of the header, query or cookie parameter to be used.
	//
	// Applies To: apiKey
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// REQUIRED.
	// The location of the API key.
	// Valid values are "query", "header" or "cookie".
	//
	// Applies To: apiKey
	In string `json:"in,omitempty" yaml:"in,omitempty"`
	// REQUIRED.
	// The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
	// The values used SHOULD be registered in the IANA Authentication Scheme registry.
	//
	// Applies To: http
	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`
	// A hint to the client to identify how the bearer token is formatted.
	// Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
	//
	// Applies To: http ("bearer")
	BearerFormat string `json:"bearerFormat,omitempty" yaml:"bearerFormat,omitempty"`
	// REQUIRED.
	// An object containing configuration information for the flow types supported.
	//
	// Applies To: oauth2
	Flows *Extendable[OAuthFlows] `json:"flows,omitempty" yaml:"flows,omitempty"`
	// REQUIRED.
	// OpenId Connect URL to discover OAuth2 configuration values.
	// This MUST be in the form of a URL.
	// The OpenID Connect standard requires the use of TLS.
	//
	// Applies To: openIdConnect
	OpenIDConnectURL string `json:"openIdConnectUrl,omitempty" yaml:"openIdConnectUrl,omitempty"`
}

SecurityScheme defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749], and OpenID Connect Discovery. Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use case is Authorization Code Grant flow with PKCE.

https://spec.openapis.org/oas/v3.1.1#security-scheme-object

Example: 

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

type SecuritySchemeBuilder 

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

func NewSecuritySchemeBuilder 

func NewSecuritySchemeBuilder() *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) AddExt 

func (b *SecuritySchemeBuilder) AddExt(name string, value any) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) BearerFormat 

func (b *SecuritySchemeBuilder) BearerFormat(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Build 

func (b *SecuritySchemeBuilder) Build() *RefOrSpec[Extendable[SecurityScheme]]

func (*SecuritySchemeBuilder) Description 

func (b *SecuritySchemeBuilder) Description(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Extensions 

func (b *SecuritySchemeBuilder) Extensions(v map[string]any) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Flows 

func (b *SecuritySchemeBuilder) Flows(v *Extendable[OAuthFlows]) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) In 

func (b *SecuritySchemeBuilder) In(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Name 

func (b *SecuritySchemeBuilder) Name(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) OpenIDConnectURL 

func (b *SecuritySchemeBuilder) OpenIDConnectURL(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Scheme 

func (b *SecuritySchemeBuilder) Scheme(v string) *SecuritySchemeBuilder

func (*SecuritySchemeBuilder) Type 

func (b *SecuritySchemeBuilder) Type(v string) *SecuritySchemeBuilder

type Server 

type Server struct {
	// A map between a variable name and its value.
	// The value is used for substitution in the server’s URL template.
	Variables map[string]*Extendable[ServerVariable] `json:"variables,omitempty" yaml:"variables,omitempty"`
	// REQUIRED.
	// A URL to the target host.
	// This URL supports Server Variables and MAY be relative, to indicate that the host location is relative
	// to the location where the OpenAPI document is being served.
	// Variable substitutions will be made when a variable is named in {brackets}.
	URL string `json:"url" yaml:"url"`
	// An optional string describing the host designated by the URL.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Server is an object representing a Server.

https://spec.openapis.org/oas/v3.1.1#server-object

Example: 

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

type ServerBuilder 

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

func NewServerBuilder 

func NewServerBuilder() *ServerBuilder

func (*ServerBuilder) AddExt 

func (b *ServerBuilder) AddExt(name string, value any) *ServerBuilder

func (*ServerBuilder) AddVariable 

func (b *ServerBuilder) AddVariable(name string, value *Extendable[ServerVariable]) *ServerBuilder

func (*ServerBuilder) Build 

func (b *ServerBuilder) Build() *Extendable[Server]

func (*ServerBuilder) Description 

func (b *ServerBuilder) Description(v string) *ServerBuilder

func (*ServerBuilder) Extensions 

func (b *ServerBuilder) Extensions(v map[string]any) *ServerBuilder

func (*ServerBuilder) URL 

func (b *ServerBuilder) URL(v string) *ServerBuilder

func (*ServerBuilder) Variables 

func (b *ServerBuilder) Variables(v map[string]*Extendable[ServerVariable]) *ServerBuilder

type ServerVariable 

type ServerVariable struct {
	// REQUIRED.
	// The default value to use for substitution, which SHALL be sent if an alternate value is not supplied.
	// Note this behavior is different than the Schema Object’s treatment of default values,
	// because in those cases parameter values are optional.
	// If the enum is defined, the value MUST exist in the enum’s values.
	Default string `json:"default" yaml:"default"`
	// An optional description for the server variable.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// An enumeration of string values to be used if the substitution options are from a limited set.
	// The array MUST NOT be empty.
	Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`
}

ServerVariable is an object representing a Server Variable for server URL template substitution.

https://spec.openapis.org/oas/v3.1.1#server-variable-object

type ServerVariableBuilder 

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

func NewServerVariableBuilder 

func NewServerVariableBuilder() *ServerVariableBuilder

func (*ServerVariableBuilder) AddEnum 

func (b *ServerVariableBuilder) AddEnum(v ...string) *ServerVariableBuilder

func (*ServerVariableBuilder) AddExt 

func (b *ServerVariableBuilder) AddExt(name string, value any) *ServerVariableBuilder

func (*ServerVariableBuilder) Build 

func (b *ServerVariableBuilder) Build() *Extendable[ServerVariable]

func (*ServerVariableBuilder) Default 

func (b *ServerVariableBuilder) Default(v string) *ServerVariableBuilder

func (*ServerVariableBuilder) Description 

func (b *ServerVariableBuilder) Description(v string) *ServerVariableBuilder

func (*ServerVariableBuilder) Enum 

func (b *ServerVariableBuilder) Enum(v ...string) *ServerVariableBuilder

func (*ServerVariableBuilder) Extensions 

func (b *ServerVariableBuilder) Extensions(v map[string]any) *ServerVariableBuilder

type SingleOrArray 

type SingleOrArray[T any] []T

SingleOrArray holds list or single value

func NewSingleOrArray 

func NewSingleOrArray[T any](v ...T) *SingleOrArray[T]

NewSingleOrArray creates SingleOrArray object.

func (*SingleOrArray[T]) Add 

func (o *SingleOrArray[T]) Add(v ...T) *SingleOrArray[T]

func (*SingleOrArray[T]) MarshalJSON 

func (o *SingleOrArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*SingleOrArray[T]) MarshalYAML 

func (o *SingleOrArray[T]) MarshalYAML() (any, error)

MarshalYAML implements yaml.Marshaler interface.

func (*SingleOrArray[T]) UnmarshalJSON 

func (o *SingleOrArray[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*SingleOrArray[T]) UnmarshalYAML 

func (o *SingleOrArray[T]) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

type SpecNotFoundError 

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

func (*SpecNotFoundError) Error 

func (e *SpecNotFoundError) Error() string

func (*SpecNotFoundError) Is 

func (e *SpecNotFoundError) Is(target error) bool

type Tag 

type Tag struct {
	// Additional external documentation for this tag.
	ExternalDocs *Extendable[ExternalDocs] `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// REQUIRED.
	// The name of the tag.
	Name string `json:"name" yaml:"name"`
	// A description for the tag.
	// CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Tag adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.

https://spec.openapis.org/oas/v3.1.1#tag-object

Example: 

name: pet
description: Pets operations

type TagBuilder 

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

func NewTagBuilder 

func NewTagBuilder() *TagBuilder

func (*TagBuilder) AddExt 

func (b *TagBuilder) AddExt(name string, value any) *TagBuilder

func (*TagBuilder) Build 

func (b *TagBuilder) Build() *Extendable[Tag]

func (*TagBuilder) Description 

func (b *TagBuilder) Description(v string) *TagBuilder

func (*TagBuilder) Extensions 

func (b *TagBuilder) Extensions(v map[string]any) *TagBuilder

func (*TagBuilder) ExternalDocs 

func (b *TagBuilder) ExternalDocs(v *Extendable[ExternalDocs]) *TagBuilder

func (*TagBuilder) Name 

func (b *TagBuilder) Name(v string) *TagBuilder

type UnsupportedSpecTypeError 

type UnsupportedSpecTypeError string

func (UnsupportedSpecTypeError) Error 

func (e UnsupportedSpecTypeError) Error() string

func (UnsupportedSpecTypeError) Is 

func (e UnsupportedSpecTypeError) Is(target error) bool

type UnsupportedTypeError 

type UnsupportedTypeError string

func (UnsupportedTypeError) Error 

func (e UnsupportedTypeError) Error() string

func (UnsupportedTypeError) Is 

func (e UnsupportedTypeError) Is(target error) bool

type UnsupportedVersionError 

type UnsupportedVersionError string

func (UnsupportedVersionError) Error 

func (e UnsupportedVersionError) Error() string

func (UnsupportedVersionError) Is 

func (e UnsupportedVersionError) Is(err error) bool

type ValidationOption 

type ValidationOption func(*validationOptions)

ValidationOption is a type for validation options.

func AllowExtensionNameWithoutPrefix 

func AllowExtensionNameWithoutPrefix() ValidationOption

AllowExtensionNameWithoutPrefix is a validation option to allow extension name without `x-` prefix.

func AllowRequestBodyForDelete 

func AllowRequestBodyForDelete() ValidationOption

AllowRequestBodyForDelete is a validation option to allow request body for DELETE operation.

func AllowRequestBodyForGet 

func AllowRequestBodyForGet() ValidationOption

AllowRequestBodyForGet is a validation option to allow request body for GET operation.

func AllowRequestBodyForHead 

func AllowRequestBodyForHead() ValidationOption

AllowRequestBodyForHead is a validation option to allow request body for HEAD operation.

func AllowUndefinedTagsInOperation 

func AllowUndefinedTagsInOperation() ValidationOption

AllowUndefinedTagsInOperation is a validation option to allow undefined tags in operation.

func AllowUnusedComponents 

func AllowUnusedComponents() ValidationOption

AllowUnusedComponents is a validation option to allow unused components.

func DoNotValidateDefaultValues 

func DoNotValidateDefaultValues() ValidationOption

DoNotValidateDefaultValues is a validation option to skip default values validation.

func DoNotValidateExamples 

func DoNotValidateExamples() ValidationOption

DoNotValidateExamples is a validation option to skip examples validation.

func UpdateCompiler 

func UpdateCompiler(f func(*jsonschema.Compiler)) ValidationOption

UpdateCompiler is a type to modify the jsonschema.Compiler.

func ValidateStringDataAsJSON 

func ValidateStringDataAsJSON() ValidationOption

type Validator 

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

Validator is a struct for validating the OpenAPI specification and a data.

func NewValidator 

func NewValidator(spec *Extendable[OpenAPI], opts ...ValidationOption) (*Validator, error)

NewValidator creates an instance of Validator struct.

The function creates new jsonschema comppiler and adds the given spec to the compiler.

func (*Validator) ValidateData 

func (v *Validator) ValidateData(location string, value any) error

ValidateData validates the given value against the schema located at the given location.

The location should be in form of JSON Pointer. The value can be a struct, a string containing JSON, or any other types. If the value is a struct, it will be marshaled and unmarshaled to JSON.

func (*Validator) ValidateDataAsJSON 

func (v *Validator) ValidateDataAsJSON(location string, value any) error

ValidateDataAsJSON marshal and unmarshals the given value to JSON and validates it against the schema located at the given location.

If the value is a string, it will be unmarshaled to JSON first, if failed it will be kept as is.

func (*Validator) ValidateSpec 

func (v *Validator) ValidateSpec() error

ValidateSpec validates the specification.

type Webhooks 

type Webhooks = map[string]*RefOrSpec[Extendable[PathItem]]

func NewWebhooks 

func NewWebhooks() Webhooks

type XML 

type XML struct {
	// Replaces the name of the element/attribute used for the described schema property.
	// When defined within items, it will affect the name of the individual XML elements within the list.
	// When defined alongside type being array (outside the items), it will affect the wrapping element and only if wrapped is true.
	// If wrapped is false, it will be ignored.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// The URI of the namespace definition.
	// This MUST be in the form of an absolute URI.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	// The prefix to be used for the name.
	Prefix string `json:"prefix,omitempty" yaml:"prefix,omitempty"`
	// Declares whether the property definition translates to an attribute instead of an element. Default value is false.
	Attribute bool `json:"attribute,omitempty" yaml:"attribute,omitempty"`
	// MAY be used only for an array definition.
	// Signifies whether the array is wrapped (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>).
	// Default value is false.
	// The definition takes effect only when defined alongside type being array (outside the items).
	Wrapped bool `json:"wrapped,omitempty" yaml:"wrapped,omitempty"`
}

XML is a metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are not inferred (for singular/plural forms) and the name property SHOULD be used to add that information. See examples for expected behavior.

https://spec.openapis.org/oas/v3.1.1#xml-object

Example: 

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://example.com/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
</Person>

type XMLBuilder 

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

func NewXMLBuilder 

func NewXMLBuilder() *XMLBuilder

func (*XMLBuilder) AddExt 

func (b *XMLBuilder) AddExt(name string, value any) *XMLBuilder

func (*XMLBuilder) Attribute 

func (b *XMLBuilder) Attribute(v bool) *XMLBuilder

func (*XMLBuilder) Build 

func (b *XMLBuilder) Build() *Extendable[XML]

func (*XMLBuilder) Extensions 

func (b *XMLBuilder) Extensions(v map[string]any) *XMLBuilder

func (*XMLBuilder) Name 

func (b *XMLBuilder) Name(v string) *XMLBuilder

func (*XMLBuilder) Namespace 

func (b *XMLBuilder) Namespace(v string) *XMLBuilder

func (*XMLBuilder) Prefix 

func (b *XMLBuilder) Prefix(v string) *XMLBuilder

func (*XMLBuilder) Wrapped 

func (b *XMLBuilder) Wrapped(v bool) *XMLBuilder

Source Files

View all Source files

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.