Documentation
¶
Overview ¶
Package oaschema defines schemas for Open API resources.
Index ¶
- Constants
- Variables
- func DetectSchemaFromValue(value any) *base.Schema
- func ExtractCommonParametersOfOperation(pathParams []*highv3.Parameter, operation *highv3.Operation) []*highv3.Parameter
- func ExtractSchemaProxies(proxies []*base.SchemaProxy) []*base.Schema
- func ExtractSchemaTypes(schema *base.Schema) (types []string, allOf []*base.Schema, oneOf []*base.Schema, ...)
- func GetDefaultContentType(contents *orderedmap.Map[string, *highv3.MediaType]) string
- func GetResponseContentType(responses *highv3.Responses) string
- func GetSchemaTypes(schema *base.Schema) ([]string, bool)
- func GetUnionSchemaTypes(schemas []*base.Schema) ([]string, bool)
- func IsSchemaObjectEmpty(schema *base.Schema) bool
- func IsSchemaTypeEmpty(schema *base.Schema) bool
- func MergeDefaultOrderedMap[K comparable, V any](dest, src *orderedmap.Map[K, V]) *orderedmap.Map[K, V]
- func NormalizeType(typeName string) (string, bool)
- func SupportedSecuritySchemeTypes() []string
- type HealthCheckConfig
- type MediaType
- type OpenAPIForwardHeadersConfig
- type OpenAPIResourceDefinition
- func (j *OpenAPIResourceDefinition) Build(ctx context.Context) (*highv3.Document, []*overlay.Warning, error)
- func (j OpenAPIResourceDefinition) MarshalJSON() ([]byte, error)
- func (j *OpenAPIResourceDefinition) UnmarshalJSON(b []byte) error
- func (j *OpenAPIResourceDefinition) UnmarshalYAML(value *yaml.Node) error
- type OpenAPIResourceSettings
- type Operation
- type Parameter
- type ParameterEncodingStyle
- func (j ParameterEncodingStyle) IsValid() bool
- func (j ParameterEncodingStyle) MarshalJSON() ([]byte, error)
- func (j ParameterEncodingStyle) MarshalText() ([]byte, error)
- func (j ParameterEncodingStyle) String() string
- func (j *ParameterEncodingStyle) UnmarshalJSON(input []byte) error
- func (j *ParameterEncodingStyle) UnmarshalText(text []byte) error
- type ParameterLocation
- func (j ParameterLocation) IsValid() bool
- func (j ParameterLocation) MarshalJSON() ([]byte, error)
- func (j ParameterLocation) MarshalText() ([]byte, error)
- func (j ParameterLocation) String() string
- func (j *ParameterLocation) UnmarshalJSON(input []byte) error
- func (j *ParameterLocation) UnmarshalText(text []byte) error
- type RequestBody
- type SecuritySchemeType
- func (j SecuritySchemeType) IsValid() bool
- func (j SecuritySchemeType) MarshalJSON() ([]byte, error)
- func (j SecuritySchemeType) MarshalText() ([]byte, error)
- func (j SecuritySchemeType) String() string
- func (j *SecuritySchemeType) UnmarshalJSON(input []byte) error
- func (j *SecuritySchemeType) UnmarshalText(text []byte) error
Constants ¶
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" )
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" )
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" )
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 = "/" )
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 ¶
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", ) )
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 ¶
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 ¶
GetDefaultContentType gets the default content type from the content map.
func GetResponseContentType ¶
GetResponseContentType gets the successful content type of the operation.
func GetSchemaTypes ¶
GetSchemaTypes returns available types of the schema, and check if it is nullable.
func GetUnionSchemaTypes ¶
GetUnionSchemaTypes returns unique types of union schemas.
func IsSchemaObjectEmpty ¶
IsSchemaObjectEmpty checks if the schema object is empty.
func IsSchemaTypeEmpty ¶
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 ¶
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 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 ¶
func (j *OpenAPIResourceDefinition) Build( ctx context.Context, ) (*highv3.Document, []*overlay.Warning, error)
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.
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¶mName[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 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.