oaschema

package
v0.0.0-...-8c81104 Latest Latest
Warning

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

Go to latest
Published: Jun 28, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package oaschema defines schemas for Open API resources.

Index

Constants

View Source
const (
	// XRelyServerWeight is the extension name enum for the weight of server if the load balancer is configured.
	XRelyServerWeight = "x-rely-server-weight"
	// XRelyServerHeaders is the extension name enum for custom headers for the server.
	XRelyServerHeaders = "x-rely-server-headers"
	// XRelyServerTLS is the extension name enum for a server TLS config.
	XRelyServerTLS = "x-rely-server-tls"
	// XRelyProxyAction is the extension name enum for a proxy action.
	XRelyProxyAction = "x-rely-proxy-action"
	// XRelySecurityCredentials is the extension name enum for security credentials.
	XRelySecurityCredentials = "x-rely-security-credentials"
	// XRelyOAuth2TokenURLEnv is the extension name enum of a custom environment variable for OAuth2 token URL.
	XRelyOAuth2TokenURLEnv = "x-rely-oauth2-token-url-env" //nolint:gosec
	// XRelyOAuth2RefreshURLEnv is the extension name enum of a custom environment variable for OAuth2 refresh URL.
	XRelyOAuth2RefreshURLEnv = "x-rely-oauth2-refresh-url-env"
)
View Source
const (
	// Integer represents the constant of an integer type.
	Integer = "integer"
	// Number represents the constant of a number type.
	Number = "number"
	// Object represents the constant of an object type.
	Object = "object"
	// String represents the constant of a string type.
	String = "string"
	// Array represents the constant of an array type.
	Array = "array"
	// Boolean represents the constant of a boolean type.
	Boolean = "boolean"
	// Null represents the constant of a nullable type.
	Null = "null"
)
View Source
const (
	// Date represents the full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21.
	Date = "date"
	// DateTime represents the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z.
	DateTime = "date-time"
	// Password represents a hint to UIs to mask the input.
	Password = "password"
	// Byte represents base64-encoded characters, for example, U3dhZ2dlciByb2Nrcw==.
	Byte = "byte"
	// Binary represents the binary data, used to describe files.
	Binary = "binary"
	// Email represents an email string. It is a hint to UIs to render the form.
	Email = "email"
	// UUID represents a UUID string.
	UUID = "uuid"
	// URI represents a URI string.
	URI = "uri"
	// Hostname represents an hostname string.
	Hostname = "hostname"
	// IPv4 represents an IPv4 string.
	IPv4 = "ipv4"
	// IPv6 represents an IPv6 string.
	IPv6 = "ipv6"
	// Float represents floating-point numbers.
	Float = "float"
	// Double represents floating-point numbers with double precision.
	Double = "double"
	// Int32 represents signed 32-bit integers (commonly used integer type).
	Int32 = "int32"
	// Int64 represents signed 64-bit integers (long type).
	Int64 = "int64"
)
View Source
const (
	// Pipe presents the constant of a pipe character.
	Pipe = "|"
	// Comma presents the constant of a comma character.
	Comma = ","
	// Space presents the constant of a space character.
	Space = " "
	// SemiColon presents the constant of a semicolon character.
	SemiColon = ";"
	// Asterisk presents the constant of a asterisk character.
	Asterisk = "*"
	// Dot presents the constant of a dot character.
	Dot = "."
	// Equals presents the constant of an equality character.
	Equals = "="
	// Slash presents the constant of aa slash character.
	Slash = "/"
)
View Source
const (
	// CookieKey represents the constant string of a cookie.
	CookieKey = "cookie"
	// QueryKey represents the constant string of a query.
	QueryKey = "query"
	// HeaderKey represents the constant string of a header.
	HeaderKey = "header"
	// PathKey represents the constant string of a path.
	PathKey = "path"
	// BodyKey represents the constant string of a body.
	BodyKey = "body"
	// FormDataKey represents the constant string of a form data.
	FormDataKey = "formData"
)

Variables

View Source
var (
	// ErrInvalidParameterLocation occurs when the parameter location is invalid.
	ErrInvalidParameterLocation = fmt.Errorf(
		"invalid ParameterLocation. Expected one of %v",
		enumValueParameterLocations,
	)
	// ErrInvalidParameterEncodingStyle occurs when the parameter location is invalid.
	ErrInvalidParameterEncodingStyle = fmt.Errorf(
		"invalid ParameterEncodingStyle. Expected one of %v",
		enumValueEncodingStyles,
	)
	// ErrInvalidSecuritySchemeType occurs when the security scheme type is invalid.
	ErrInvalidSecuritySchemeType = fmt.Errorf(
		"invalid SecuritySchemeType. Expected one of %v",
		SupportedSecuritySchemeTypes(),
	)
	// ErrResourceSpecRequired occurs when the spec field of resource is empty.
	ErrResourceSpecRequired = errors.New("either spec or ref is required for the OpenAPI document")
	// ErrInvalidOpenAPIResourceDefinition occurs when failing to parse a OpenAPIResourceDefinition from YAML string.
	ErrInvalidOpenAPIResourceDefinition = errors.New(
		"invalid OpenAPIResourceDefinition",
	)
)
View Source
var (
	ErrInvalidOpenAPIv3Spec = errors.New(
		"spec is defined as an OpenAPI 3.x, but is using a swagger (2.0), or unknown version",
	)
	ErrInvalidOpenAPIVersion = errors.New("unable to extract OpenAPI version")
)

Functions

func DetectSchemaFromValue

func DetectSchemaFromValue(value any) *base.Schema

DetectSchemaFromValue detects the OpenAPI schema type from a Go value.

func ExtractCommonParametersOfOperation

func ExtractCommonParametersOfOperation(
	pathParams []*highv3.Parameter,
	operation *highv3.Operation,
) []*highv3.Parameter

ExtractCommonParametersOfOperation extracts common parameters from operation's parameters.

func ExtractSchemaProxies

func ExtractSchemaProxies(proxies []*base.SchemaProxy) []*base.Schema

ExtractSchemaProxies returns schema references of schema proxies.

func ExtractSchemaTypes

func ExtractSchemaTypes(schema *base.Schema) (
	types []string,
	allOf []*base.Schema,
	oneOf []*base.Schema,
	anyOf []*base.Schema,
	isNullable bool,
)

ExtractSchemaTypes returns available types of the schema, and check if it is nullable.

func GetDefaultContentType

func GetDefaultContentType(contents *orderedmap.Map[string, *highv3.MediaType]) string

GetDefaultContentType gets the default content type from the content map.

func GetResponseContentType

func GetResponseContentType(responses *highv3.Responses) string

GetResponseContentType gets the successful content type of the operation.

func GetSchemaTypes

func GetSchemaTypes(schema *base.Schema) ([]string, bool)

GetSchemaTypes returns available types of the schema, and check if it is nullable.

func GetUnionSchemaTypes

func GetUnionSchemaTypes(schemas []*base.Schema) ([]string, bool)

GetUnionSchemaTypes returns unique types of union schemas.

func IsSchemaObjectEmpty

func IsSchemaObjectEmpty(schema *base.Schema) bool

IsSchemaObjectEmpty checks if the schema object is empty.

func IsSchemaTypeEmpty

func IsSchemaTypeEmpty(schema *base.Schema) bool

IsSchemaTypeEmpty checks if the schema type is empty.

func MergeDefaultOrderedMap

func MergeDefaultOrderedMap[K comparable, V any](
	dest, src *orderedmap.Map[K, V],
) *orderedmap.Map[K, V]

MergeDefaultOrderedMap assigns properties of the source order map to another. Existing properties will not be assigned.

func NormalizeType

func NormalizeType(typeName string) (string, bool)

NormalizeType normalize a schema type. Returns the type name and whether if it is a primitive type.

func SupportedSecuritySchemeTypes

func SupportedSecuritySchemeTypes() []string

SupportedSecuritySchemeTypes return all supported security scheme types.

Types

type HealthCheckConfig

type HealthCheckConfig struct {
	// Configurations for health check through HTTP protocol.
	HTTP *loadbalancer.HTTPHealthCheckConfig `json:"http,omitempty" yaml:"http,omitempty"`
}

HealthCheckConfig holds health check configurations for server recovery.

type MediaType

type MediaType struct {
	ContentType  string
	Schema       *base.Schema
	ItemSchema   *base.Schema
	Encoding     *orderedmap.Map[string, *highv3.Encoding]
	ItemEncoding *orderedmap.Map[string, *highv3.Encoding]
}

type OpenAPIForwardHeadersConfig

type OpenAPIForwardHeadersConfig struct {
	// Defines header names to be forwarded from the client request.
	Request []string `json:"request,omitempty" yaml:"request,omitempty"`
	// Defines header names to be forwarded from the response.
	Response []string `json:"response,omitempty" yaml:"response,omitempty"`
}

OpenAPIForwardHeadersConfig contains configurations for headers forwarding,.

type OpenAPIResourceDefinition

type OpenAPIResourceDefinition struct {
	// Settings of the OpenAPI resource.
	Settings *OpenAPIResourceSettings `json:"settings,omitempty" yaml:"settings,omitempty"`
	// Path of URL of the referenced OpenAPI document.
	// Requires at least one of ref or spec.
	// If both fields are configured, the spec will be merged into the reference.
	Ref string `json:"ref,omitempty" yaml:"ref,omitempty"`
	// Specification of the OpenAPI v3 documentation.
	Spec *yaml.Node `json:"spec,omitempty" yaml:"spec,omitempty"`
	// A set of patches, or [overlay actions] to be applied to one or many OpenAPI descriptions.
	//
	// [overlay actions]: https://spec.openapis.org/overlay/v1.1.0.html#action-object
	Patches *yaml.Node `json:"patches,omitempty" yaml:"patches,omitempty"`
}

OpenAPIResourceDefinition defines fields of an OpenAPI resource.

func (*OpenAPIResourceDefinition) Build

Build validates and merge the openapi specification with the reference if exist.

func (OpenAPIResourceDefinition) MarshalJSON

func (j OpenAPIResourceDefinition) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*OpenAPIResourceDefinition) UnmarshalJSON

func (j *OpenAPIResourceDefinition) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*OpenAPIResourceDefinition) UnmarshalYAML

func (j *OpenAPIResourceDefinition) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements the yaml.Unmarshaler interface.

type OpenAPIResourceSettings

type OpenAPIResourceSettings struct {
	// Base path of the resource.
	BasePath string `json:"basePath,omitempty" yaml:"basePath,omitempty"`
	// Global settings for the HTTP client.
	HTTP *httpconfig.HTTPClientConfig `json:"http,omitempty" yaml:"http,omitempty"`
	// Headers define custom headers to be injected to the remote server.
	// Merged with the global headers.
	Headers map[string]goenvconf.EnvString `json:"headers,omitempty" yaml:"headers,omitempty"`
	// ForwardHeaders define configurations for headers forwarding
	ForwardHeaders *OpenAPIForwardHeadersConfig `json:"forwardHeaders,omitempty" yaml:"forwardHeaders,omitempty"`
	// HealthCheck define the health check policy for load balancer recovery.
	HealthCheck *HealthCheckConfig `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`
	// Enable or disable the strict validation mode.
	Strict bool `json:"strict,omitempty" yaml:"strict,omitempty"`
}

OpenAPIResourceSettings hold settings of the rely proxy.

type Operation

type Operation struct {
	OperationID string
	Parameters  []*Parameter
	RequestBody *RequestBody
	Responses   map[string]*MediaType
	Security    []*base.SecurityRequirement
	Servers     []*highv3.Server
	Extensions  *orderedmap.Map[string, *yaml.Node]
}

type Parameter

type Parameter struct {
	// The name of the parameter.
	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.
	Explode *bool `json:"explode,omitempty" yaml:"explode,omitempty"`
	// When this is true, parameter values are serialized using reserved expansion.
	AllowReserved bool `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
	// Whether the parameter is required.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`
	// The location of the parameter.
	In ParameterLocation `json:"in" yaml:"in" jsonschema:"type=string,enum=header,enum=query,enum=cookie,enum=path"`
	// Describes how the parameter value will be serialized depending on the type of the parameter value.
	Style *ParameterEncodingStyle `` /* 158-byte string literal not displayed */
	// Schema of the parameter.
	Schema *base.Schema `json:"-" yaml:"-"`
	// Optional con
	Content *MediaType `json:"-" yaml:"-"`
}

Parameter represents an object of common configurations for a parameter.

func (Parameter) GetStyleAndExplode

func (param Parameter) GetStyleAndExplode() (ParameterEncodingStyle, bool)

GetStyleAndExplode gets the matched explode value of the parameter location.

func (Parameter) Validate

func (param Parameter) Validate() error

Validate checks if the current parameter config is valid.

type ParameterEncodingStyle

type ParameterEncodingStyle uint8

ParameterEncodingStyle represents the encoding style of the parameter. style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.

const (
	// EncodingStyleSimple (default of query) comma-separated values. Corresponds to the {param_name} URI template.
	EncodingStyleSimple ParameterEncodingStyle = iota
	// EncodingStyleLabel dot-prefixed values, also known as label expansion. Corresponds to the {.param_name} URI template.
	EncodingStyleLabel
	// EncodingStyleMatrix semicolon-prefixed values, also known as path-style expansion. Corresponds to the {;param_name} URI template.
	EncodingStyleMatrix
	// EncodingStyleForm ampersand-separated values, also known as form-style query expansion. Corresponds to the {?param_name} URI template.
	EncodingStyleForm
	// EncodingStyleSpaceDelimited space-separated array values. Same as collectionFormat: ssv in OpenAPI 2.0.
	// Has effect only for non-exploded arrays (explode: false), that is, the space separates the array values if the array is a single parameter, as in arr=a b c.
	EncodingStyleSpaceDelimited
	// EncodingStylePipeDelimited pipeline-separated array values. Same as collectionFormat: pipes in OpenAPI 2.0.
	// Has effect only for non-exploded arrays (explode: false), that is, the pipe separates the array values if the array is a single parameter, as in arr=a|b|c.
	EncodingStylePipeDelimited
	// EncodingStyleDeepObject simple non-nested objects are serialized as paramName[prop1]=value1&paramName[prop2]=value2&....
	// The behavior for nested objects and arrays is undefined.
	EncodingStyleDeepObject
	// EncodingStyleCookie is analogous to form, but following [RFC6265] Cookie syntax rules,
	// meaning that name-value pairs are separated by a semicolon followed by a single space (e.g. n1=v1; n2=v2),
	// and no percent-encoding or other escaping is applied; data values that require any sort of escaping MUST be provided in escaped form.
	//
	// [RFC6265]: https://datatracker.ietf.org/doc/html/rfc6265#section-4.2.1
	EncodingStyleCookie
)

func GetParameterStyleAndExplode

func GetParameterStyleAndExplode(
	location ParameterLocation,
	style *ParameterEncodingStyle,
	explode *bool,
) (ParameterEncodingStyle, bool)

GetParameterStyleAndExplode applies the OpenAPI defaults for style and explode per location:

  • path / header: default style=simple, default explode=false
  • query / cookie: default style=form, default explode=true

func ParseParameterEncodingStyle

func ParseParameterEncodingStyle(input string) (ParameterEncodingStyle, error)

ParseParameterEncodingStyle parses ParameterEncodingStyle from string.

func (ParameterEncodingStyle) IsValid

func (j ParameterEncodingStyle) IsValid() bool

IsValid checks if the style enum is valid.

func (ParameterEncodingStyle) MarshalJSON

func (j ParameterEncodingStyle) MarshalJSON() ([]byte, error)

MarshalJSON marshals themselves into valid JSON.

func (ParameterEncodingStyle) MarshalText

func (j ParameterEncodingStyle) MarshalText() ([]byte, error)

MarshalText encodes the receiver into UTF-8-encoded text and returns the result.

func (ParameterEncodingStyle) String

func (j ParameterEncodingStyle) String() string

String implements fmt.Stringer interface.

func (*ParameterEncodingStyle) UnmarshalJSON

func (j *ParameterEncodingStyle) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals a JSON description of themselves.

func (*ParameterEncodingStyle) UnmarshalText

func (j *ParameterEncodingStyle) UnmarshalText(text []byte) error

UnmarshalText must be able to decode the form generated by MarshalText.

type ParameterLocation

type ParameterLocation uint8

ParameterLocation is the location of the parameter.

const (
	// InQuery is the constant enum that indicates the parameter location in query.
	InQuery ParameterLocation = iota
	// InHeader is the constant enum that indicates the parameter location in header.
	InHeader
	// InPath is the constant enum that indicates the parameter location in path.
	InPath
	// InCookie is the constant enum that indicates the parameter location in cookie.
	InCookie
	// InBody is the constant enum that indicates the parameter location in body.
	InBody
	// InFormData is the constant enum that indicates the parameter location in formData.
	InFormData
)

func ParseParameterLocation

func ParseParameterLocation(input string) (ParameterLocation, error)

ParseParameterLocation parses ParameterLocation from string.

func (ParameterLocation) IsValid

func (j ParameterLocation) IsValid() bool

IsValid checks if the style enum is valid.

func (ParameterLocation) MarshalJSON

func (j ParameterLocation) MarshalJSON() ([]byte, error)

MarshalJSON marshals themselves into valid JSON.

func (ParameterLocation) MarshalText

func (j ParameterLocation) MarshalText() ([]byte, error)

MarshalText encodes the receiver into UTF-8-encoded text and returns the result.

func (ParameterLocation) String

func (j ParameterLocation) String() string

String implements fmt.Stringer interface.

func (*ParameterLocation) UnmarshalJSON

func (j *ParameterLocation) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals a JSON description of themselves.

func (*ParameterLocation) UnmarshalText

func (j *ParameterLocation) UnmarshalText(text []byte) error

UnmarshalText must be able to decode the form generated by MarshalText.

type RequestBody

type RequestBody struct {
	Required bool
	Content  *MediaType
}

type SecuritySchemeType

type SecuritySchemeType uint8

SecuritySchemeType represents the authentication scheme enum.

const (
	APIKeyScheme SecuritySchemeType = iota
	BasicAuthScheme
	CookieAuthScheme
	HTTPAuthScheme
	OAuth2Scheme
	OpenIDConnectScheme
	MutualTLSScheme
)

func ParseSecuritySchemeType

func ParseSecuritySchemeType(value string) (SecuritySchemeType, error)

ParseSecuritySchemeType parses SecurityScheme from string.

func (SecuritySchemeType) IsValid

func (j SecuritySchemeType) IsValid() bool

IsValid checks if the style enum is valid.

func (SecuritySchemeType) MarshalJSON

func (j SecuritySchemeType) MarshalJSON() ([]byte, error)

MarshalJSON marshals themselves into valid JSON.

func (SecuritySchemeType) MarshalText

func (j SecuritySchemeType) MarshalText() ([]byte, error)

MarshalText encodes the receiver into UTF-8-encoded text and returns the result.

func (SecuritySchemeType) String

func (j SecuritySchemeType) String() string

String implements fmt.Stringer interface.

func (*SecuritySchemeType) UnmarshalJSON

func (j *SecuritySchemeType) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals a JSON description of themselves.

func (*SecuritySchemeType) UnmarshalText

func (j *SecuritySchemeType) UnmarshalText(text []byte) error

UnmarshalText must be able to decode the form generated by MarshalText.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL