export

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2025 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package export provides OpenAPI specification export functionality. It supports exporting to OpenAPI 3.0.x and 3.1.x formats with proper down-leveling of 3.1-only features when targeting 3.0.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CallbackV30 

type CallbackV30 struct {
	Ref        string                  `json:"$ref,omitempty"`
	PathItems  map[string]*PathItemV30 `json:"-"`
	Extensions map[string]any          `json:"-"`
}

CallbackV30 represents a callback.

func (*CallbackV30) MarshalJSON 

func (c *CallbackV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for CallbackV30. Callbacks are maps of path expressions to PathItems, so PathItems become the top-level keys.

type CallbackV31 

type CallbackV31 struct {
	Ref        string                  `json:"$ref,omitempty"`
	PathItems  map[string]*PathItemV31 `json:"-"`
	Extensions map[string]any          `json:"-"`
}

CallbackV31 represents a callback.

func (*CallbackV31) MarshalJSON 

func (c *CallbackV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for CallbackV31. Callbacks are maps of path expressions to PathItems, so PathItems become the top-level keys.

type ComponentsV30 

type ComponentsV30 struct {
	Schemas         map[string]*SchemaV30         `json:"schemas,omitempty"`
	Responses       map[string]*ResponseV30       `json:"responses,omitempty"`
	Parameters      map[string]*ParameterV30      `json:"parameters,omitempty"`
	Examples        map[string]*ExampleV30        `json:"examples,omitempty"`
	RequestBodies   map[string]*RequestBodyV30    `json:"requestBodies,omitempty"`
	Headers         map[string]*HeaderV30         `json:"headers,omitempty"`
	SecuritySchemes map[string]*SecuritySchemeV30 `json:"securitySchemes,omitempty"`
	Links           map[string]*LinkV30           `json:"links,omitempty"`
	Callbacks       map[string]*CallbackV30       `json:"callbacks,omitempty"`
	Extensions      map[string]any                `json:"-"`
}

ComponentsV30 holds reusable components.

func (*ComponentsV30) MarshalJSON 

func (c *ComponentsV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ComponentsV30 to inline extensions.

type ComponentsV31 

type ComponentsV31 struct {
	Schemas         map[string]*SchemaV31         `json:"schemas,omitempty"`
	Responses       map[string]*ResponseV31       `json:"responses,omitempty"`
	Parameters      map[string]*ParameterV31      `json:"parameters,omitempty"`
	Examples        map[string]*ExampleV31        `json:"examples,omitempty"`
	RequestBodies   map[string]*RequestBodyV31    `json:"requestBodies,omitempty"`
	Headers         map[string]*HeaderV31         `json:"headers,omitempty"`
	SecuritySchemes map[string]*SecuritySchemeV31 `json:"securitySchemes,omitempty"`
	Links           map[string]*LinkV31           `json:"links,omitempty"`
	Callbacks       map[string]*CallbackV31       `json:"callbacks,omitempty"`
	PathItems       map[string]*PathItemV31       `json:"pathItems,omitempty"` // 3.1 only
	Extensions      map[string]any                `json:"-"`
}

ComponentsV31 holds reusable components.

func (*ComponentsV31) MarshalJSON 

func (c *ComponentsV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ComponentsV31 to inline extensions.

type Config 

type Config struct {
	// Version is the target OpenAPI version.
	Version Version

	// StrictDownlevel causes projection to error (instead of warn) when
	// 3.1-only features are used with a 3.0 target.
	StrictDownlevel bool

	// Validator is an optional validator for the generated specification.
	// If nil, no validation is performed.
	Validator Validator
}

Config configures spec projection behavior.

type ContactV30 

type ContactV30 struct {
	Name       string         `json:"name,omitempty"`
	URL        string         `json:"url,omitempty"`
	Email      string         `json:"email,omitempty"`
	Extensions map[string]any `json:"-"`
}

ContactV30 provides contact information.

func (*ContactV30) MarshalJSON 

func (c *ContactV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ContactV30 to inline extensions.

type ContactV31 

type ContactV31 struct {
	Name       string         `json:"name,omitempty"`
	URL        string         `json:"url,omitempty"`
	Email      string         `json:"email,omitempty"`
	Extensions map[string]any `json:"-"`
}

ContactV31 provides contact information.

func (*ContactV31) MarshalJSON 

func (c *ContactV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ContactV31 to inline extensions.

type DiscriminatorV30 

type DiscriminatorV30 struct {
	PropertyName string            `json:"propertyName"`
	Mapping      map[string]string `json:"mapping,omitempty"`
}

DiscriminatorV30 is used for polymorphism in oneOf/allOf compositions.

type DiscriminatorV31 

type DiscriminatorV31 struct {
	PropertyName string            `json:"propertyName"`
	Mapping      map[string]string `json:"mapping,omitempty"`
}

DiscriminatorV31 is used for polymorphism in oneOf/allOf compositions.

type EncodingV30 

type EncodingV30 struct {
	ContentType   string                `json:"contentType,omitempty"`
	Headers       map[string]*HeaderV30 `json:"headers,omitempty"`
	Style         string                `json:"style,omitempty"`
	Explode       bool                  `json:"explode,omitempty"`
	AllowReserved bool                  `json:"allowReserved,omitempty"`
	Extensions    map[string]any        `json:"-"`
}

EncodingV30 describes encoding for a schema property.

func (*EncodingV30) MarshalJSON 

func (e *EncodingV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for EncodingV30 to inline extensions.

type EncodingV31 

type EncodingV31 struct {
	ContentType   string                `json:"contentType,omitempty"`
	Headers       map[string]*HeaderV31 `json:"headers,omitempty"`
	Style         string                `json:"style,omitempty"`
	Explode       bool                  `json:"explode,omitempty"`
	AllowReserved bool                  `json:"allowReserved,omitempty"`
	Extensions    map[string]any        `json:"-"`
}

EncodingV31 describes encoding for a schema property.

func (*EncodingV31) MarshalJSON 

func (e *EncodingV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for EncodingV31 to inline extensions.

type ExampleV30 

type ExampleV30 struct {
	Ref           string         `json:"$ref,omitempty"`
	Summary       string         `json:"summary,omitempty"`
	Description   string         `json:"description,omitempty"`
	Value         any            `json:"value,omitempty"`
	ExternalValue string         `json:"externalValue,omitempty"`
	Extensions    map[string]any `json:"-"`
}

ExampleV30 represents an example value.

func (*ExampleV30) MarshalJSON 

func (e *ExampleV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ExampleV30 to inline extensions.

type ExampleV31 

type ExampleV31 struct {
	Ref           string         `json:"$ref,omitempty"`
	Summary       string         `json:"summary,omitempty"`
	Description   string         `json:"description,omitempty"`
	Value         any            `json:"value,omitempty"`
	ExternalValue string         `json:"externalValue,omitempty"`
	Extensions    map[string]any `json:"-"`
}

ExampleV31 represents an example.

func (*ExampleV31) MarshalJSON 

func (e *ExampleV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ExampleV31 to inline extensions.

type ExternalDocsV30 

type ExternalDocsV30 struct {
	Description string         `json:"description,omitempty"`
	URL         string         `json:"url"`
	Extensions  map[string]any `json:"-"`
}

ExternalDocsV30 provides external documentation.

func (*ExternalDocsV30) MarshalJSON 

func (e *ExternalDocsV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ExternalDocsV30 to inline extensions.

type ExternalDocsV31 

type ExternalDocsV31 struct {
	Description string         `json:"description,omitempty"`
	URL         string         `json:"url"`
	Extensions  map[string]any `json:"-"`
}

ExternalDocsV31 provides external documentation.

func (*ExternalDocsV31) MarshalJSON 

func (e *ExternalDocsV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ExternalDocsV31 to inline extensions.

type HeaderV30 

type HeaderV30 struct {
	Ref             string                   `json:"$ref,omitempty"`
	Description     string                   `json:"description,omitempty"`
	Required        bool                     `json:"required,omitempty"`
	Deprecated      bool                     `json:"deprecated,omitempty"`
	AllowEmptyValue bool                     `json:"allowEmptyValue,omitempty"`
	Style           string                   `json:"style,omitempty"`
	Explode         bool                     `json:"explode,omitempty"`
	Schema          *SchemaV30               `json:"schema,omitempty"`
	Example         any                      `json:"example,omitempty"`
	Examples        map[string]*ExampleV30   `json:"examples,omitempty"`
	Content         map[string]*MediaTypeV30 `json:"content,omitempty"`
	Extensions      map[string]any           `json:"-"`
}

HeaderV30 represents a response header.

func (*HeaderV30) MarshalJSON 

func (h *HeaderV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for HeaderV30 to inline extensions.

type HeaderV31 

type HeaderV31 struct {
	Ref             string                   `json:"$ref,omitempty"`
	Description     string                   `json:"description,omitempty"`
	Required        bool                     `json:"required,omitempty"`
	Deprecated      bool                     `json:"deprecated,omitempty"`
	AllowEmptyValue bool                     `json:"allowEmptyValue,omitempty"`
	Style           string                   `json:"style,omitempty"`
	Explode         bool                     `json:"explode,omitempty"`
	Schema          *SchemaV31               `json:"schema,omitempty"`
	Example         any                      `json:"example,omitempty"`
	Examples        map[string]*ExampleV31   `json:"examples,omitempty"`
	Content         map[string]*MediaTypeV31 `json:"content,omitempty"`
	Extensions      map[string]any           `json:"-"`
}

HeaderV31 represents a response header.

func (*HeaderV31) MarshalJSON 

func (h *HeaderV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for HeaderV31 to inline extensions.

type InfoV30 

type InfoV30 struct {
	Title          string         `json:"title"`
	Description    string         `json:"description,omitempty"`
	TermsOfService string         `json:"termsOfService,omitempty"`
	Version        string         `json:"version"`
	Contact        *ContactV30    `json:"contact,omitempty"`
	License        *LicenseV30    `json:"license,omitempty"`
	Extensions     map[string]any `json:"-"`
}

InfoV30 provides metadata about the API.

func (*InfoV30) MarshalJSON 

func (i *InfoV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for InfoV30 to inline extensions.

type InfoV31 

type InfoV31 struct {
	Title          string         `json:"title"`
	Summary        string         `json:"summary,omitempty"`
	Description    string         `json:"description,omitempty"`
	TermsOfService string         `json:"termsOfService,omitempty"`
	Version        string         `json:"version"`
	Contact        *ContactV31    `json:"contact,omitempty"`
	License        *LicenseV31    `json:"license,omitempty"`
	Extensions     map[string]any `json:"-"`
}

InfoV31 provides metadata about the API.

func (*InfoV31) MarshalJSON 

func (i *InfoV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for InfoV31 to inline extensions.

type InvalidExtensionKeyError 

type InvalidExtensionKeyError struct {
	Key string
}

InvalidExtensionKeyError indicates an extension key doesn't start with "x-".

func (*InvalidExtensionKeyError) Error 

func (e *InvalidExtensionKeyError) Error() string

func (*InvalidExtensionKeyError) Unwrap 

func (e *InvalidExtensionKeyError) Unwrap() error

Unwrap returns nil as InvalidExtensionKeyError is a leaf error type. This allows errors.Is() and errors.As() to work correctly.

type LicenseV30 

type LicenseV30 struct {
	Name       string         `json:"name"`
	URL        string         `json:"url,omitempty"`
	Extensions map[string]any `json:"-"`
}

LicenseV30 provides license information.

func (*LicenseV30) MarshalJSON 

func (l *LicenseV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for LicenseV30 to inline extensions.

type LicenseV31 

type LicenseV31 struct {
	Name       string         `json:"name"`                 // REQUIRED. The license name used for the API.
	Identifier string         `json:"identifier,omitempty"` // SPDX license expression. Mutually exclusive with url.
	URL        string         `json:"url,omitempty"`        // A URI for the license. Mutually exclusive with identifier.
	Extensions map[string]any `json:"-"`
}

LicenseV31 provides license information.

func (*LicenseV31) MarshalJSON 

func (l *LicenseV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for LicenseV31 to inline extensions.

type LinkV30 

type LinkV30 struct {
	Ref          string         `json:"$ref,omitempty"`
	OperationRef string         `json:"operationRef,omitempty"`
	OperationID  string         `json:"operationId,omitempty"`
	Parameters   map[string]any `json:"parameters,omitempty"`
	RequestBody  any            `json:"requestBody,omitempty"`
	Description  string         `json:"description,omitempty"`
	Server       *ServerV30     `json:"server,omitempty"`
	Extensions   map[string]any `json:"-"`
}

LinkV30 represents a design-time link for a response.

func (*LinkV30) MarshalJSON 

func (l *LinkV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for LinkV30 to inline extensions.

type LinkV31 

type LinkV31 struct {
	Ref          string         `json:"$ref,omitempty"`
	OperationRef string         `json:"operationRef,omitempty"`
	OperationID  string         `json:"operationId,omitempty"`
	Parameters   map[string]any `json:"parameters,omitempty"`
	RequestBody  any            `json:"requestBody,omitempty"`
	Description  string         `json:"description,omitempty"`
	Server       *ServerV31     `json:"server,omitempty"`
	Extensions   map[string]any `json:"-"`
}

LinkV31 represents a design-time link for a response.

func (*LinkV31) MarshalJSON 

func (l *LinkV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for LinkV31 to inline extensions.

type MediaTypeV30 

type MediaTypeV30 struct {
	Schema     *SchemaV30              `json:"schema,omitempty"`
	Example    any                     `json:"example,omitempty"`
	Examples   map[string]*ExampleV30  `json:"examples,omitempty"`
	Encoding   map[string]*EncodingV30 `json:"encoding,omitempty"`
	Extensions map[string]any          `json:"-"`
}

MediaTypeV30 provides schema and examples for a specific content type.

func (*MediaTypeV30) MarshalJSON 

func (m *MediaTypeV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for MediaTypeV30 to inline extensions.

type MediaTypeV31 

type MediaTypeV31 struct {
	Schema     *SchemaV31              `json:"schema,omitempty"`
	Example    any                     `json:"example,omitempty"`
	Examples   map[string]*ExampleV31  `json:"examples,omitempty"`
	Encoding   map[string]*EncodingV31 `json:"encoding,omitempty"`
	Extensions map[string]any          `json:"-"`
}

MediaTypeV31 provides schema and examples.

func (*MediaTypeV31) MarshalJSON 

func (m *MediaTypeV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for MediaTypeV31 to inline extensions.

type OAuthFlowV30 

type OAuthFlowV30 struct {
	AuthorizationURL string            `json:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty"`
	RefreshURL       string            `json:"refreshUrl,omitempty"`
	Scopes           map[string]string `json:"scopes"`
	Extensions       map[string]any    `json:"-"`
}

OAuthFlowV30 contains configuration details for a supported OAuth Flow.

func (*OAuthFlowV30) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OAuthFlowV30 to inline extensions.

type OAuthFlowV31 

type OAuthFlowV31 struct {
	AuthorizationURL string            `json:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty"`
	RefreshURL       string            `json:"refreshUrl,omitempty"`
	Scopes           map[string]string `json:"scopes"`
	Extensions       map[string]any    `json:"-"`
}

OAuthFlowV31 contains configuration details for a supported OAuth Flow.

func (*OAuthFlowV31) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OAuthFlowV31 to inline extensions.

type OAuthFlowsV30 

type OAuthFlowsV30 struct {
	Implicit          *OAuthFlowV30  `json:"implicit,omitempty"`
	Password          *OAuthFlowV30  `json:"password,omitempty"`
	ClientCredentials *OAuthFlowV30  `json:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlowV30  `json:"authorizationCode,omitempty"`
	Extensions        map[string]any `json:"-"`
}

OAuthFlowsV30 allows configuration of the supported OAuth Flows.

func (*OAuthFlowsV30) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OAuthFlowsV30 to inline extensions.

type OAuthFlowsV31 

type OAuthFlowsV31 struct {
	Implicit          *OAuthFlowV31  `json:"implicit,omitempty"`
	Password          *OAuthFlowV31  `json:"password,omitempty"`
	ClientCredentials *OAuthFlowV31  `json:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlowV31  `json:"authorizationCode,omitempty"`
	Extensions        map[string]any `json:"-"`
}

OAuthFlowsV31 allows configuration of the supported OAuth Flows.

func (*OAuthFlowsV31) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OAuthFlowsV31 to inline extensions.

type OperationV30 

type OperationV30 struct {
	Tags         []string                 `json:"tags,omitempty"`
	Summary      string                   `json:"summary,omitempty"`
	Description  string                   `json:"description,omitempty"`
	ExternalDocs *ExternalDocsV30         `json:"externalDocs,omitempty"`
	OperationID  string                   `json:"operationId,omitempty"`
	Parameters   []ParameterV30           `json:"parameters,omitempty"`
	RequestBody  *RequestBodyV30          `json:"requestBody,omitempty"`
	Responses    map[string]*ResponseV30  `json:"responses"`
	Callbacks    map[string]*CallbackV30  `json:"callbacks,omitempty"`
	Deprecated   bool                     `json:"deprecated,omitempty"`
	Security     []SecurityRequirementV30 `json:"security,omitempty"`
	Servers      []ServerV30              `json:"servers,omitempty"`
	Extensions   map[string]any           `json:"-"`
}

OperationV30 describes a single API operation.

func (*OperationV30) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OperationV30 to inline extensions.

type OperationV31 

type OperationV31 struct {
	Tags         []string                 `json:"tags,omitempty"`
	Summary      string                   `json:"summary,omitempty"`
	Description  string                   `json:"description,omitempty"`
	ExternalDocs *ExternalDocsV31         `json:"externalDocs,omitempty"`
	OperationID  string                   `json:"operationId,omitempty"`
	Parameters   []ParameterV31           `json:"parameters,omitempty"`
	RequestBody  *RequestBodyV31          `json:"requestBody,omitempty"`
	Responses    map[string]*ResponseV31  `json:"responses"`
	Callbacks    map[string]*CallbackV31  `json:"callbacks,omitempty"`
	Deprecated   bool                     `json:"deprecated,omitempty"`
	Security     []SecurityRequirementV31 `json:"security,omitempty"`
	Servers      []ServerV31              `json:"servers,omitempty"`
	Extensions   map[string]any           `json:"-"`
}

OperationV31 describes an API operation.

func (*OperationV31) MarshalJSON 

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

MarshalJSON implements json.Marshaler for OperationV31 to inline extensions.

type ParameterV30 

type ParameterV30 struct {
	Ref             string                   `json:"$ref,omitempty"`
	Name            string                   `json:"name,omitempty"`
	In              string                   `json:"in,omitempty"`
	Description     string                   `json:"description,omitempty"`
	Required        bool                     `json:"required,omitempty"`
	Deprecated      bool                     `json:"deprecated,omitempty"`
	AllowEmptyValue bool                     `json:"allowEmptyValue,omitempty"`
	Style           string                   `json:"style,omitempty"`
	Explode         bool                     `json:"explode,omitempty"`
	AllowReserved   bool                     `json:"allowReserved,omitempty"`
	Schema          *SchemaV30               `json:"schema,omitempty"`
	Example         any                      `json:"example,omitempty"`
	Examples        map[string]*ExampleV30   `json:"examples,omitempty"`
	Content         map[string]*MediaTypeV30 `json:"content,omitempty"`
	Extensions      map[string]any           `json:"-"`
}

ParameterV30 describes a single operation parameter.

func (*ParameterV30) MarshalJSON 

func (p *ParameterV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ParameterV30 to inline extensions.

type ParameterV31 

type ParameterV31 struct {
	Ref             string                   `json:"$ref,omitempty"`
	Name            string                   `json:"name,omitempty"`
	In              string                   `json:"in,omitempty"`
	Description     string                   `json:"description,omitempty"`
	Required        bool                     `json:"required,omitempty"`
	Deprecated      bool                     `json:"deprecated,omitempty"`
	AllowEmptyValue bool                     `json:"allowEmptyValue,omitempty"`
	Style           string                   `json:"style,omitempty"`
	Explode         bool                     `json:"explode,omitempty"`
	AllowReserved   bool                     `json:"allowReserved,omitempty"`
	Schema          *SchemaV31               `json:"schema,omitempty"`
	Example         any                      `json:"example,omitempty"`
	Examples        map[string]*ExampleV31   `json:"examples,omitempty"`
	Content         map[string]*MediaTypeV31 `json:"content,omitempty"`
	Extensions      map[string]any           `json:"-"`
}

ParameterV31 describes a parameter.

func (*ParameterV31) MarshalJSON 

func (p *ParameterV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ParameterV31 to inline extensions.

type PathItemV30 

type PathItemV30 struct {
	Ref         string         `json:"$ref,omitempty"`
	Summary     string         `json:"summary,omitempty"`
	Description string         `json:"description,omitempty"`
	Get         *OperationV30  `json:"get,omitempty"`
	Put         *OperationV30  `json:"put,omitempty"`
	Post        *OperationV30  `json:"post,omitempty"`
	Delete      *OperationV30  `json:"delete,omitempty"`
	Options     *OperationV30  `json:"options,omitempty"`
	Head        *OperationV30  `json:"head,omitempty"`
	Patch       *OperationV30  `json:"patch,omitempty"`
	Trace       *OperationV30  `json:"trace,omitempty"`
	Parameters  []ParameterV30 `json:"parameters,omitempty"`
	Extensions  map[string]any `json:"-"`
}

PathItemV30 represents the operations available on a single path.

func (*PathItemV30) MarshalJSON 

func (p *PathItemV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for PathItemV30 to inline extensions.

type PathItemV31 

type PathItemV31 struct {
	Ref         string         `json:"$ref,omitempty"`
	Summary     string         `json:"summary,omitempty"`
	Description string         `json:"description,omitempty"`
	Get         *OperationV31  `json:"get,omitempty"`
	Put         *OperationV31  `json:"put,omitempty"`
	Post        *OperationV31  `json:"post,omitempty"`
	Delete      *OperationV31  `json:"delete,omitempty"`
	Options     *OperationV31  `json:"options,omitempty"`
	Head        *OperationV31  `json:"head,omitempty"`
	Patch       *OperationV31  `json:"patch,omitempty"`
	Trace       *OperationV31  `json:"trace,omitempty"`
	Parameters  []ParameterV31 `json:"parameters,omitempty"`
	Extensions  map[string]any `json:"-"`
}

PathItemV31 represents operations on a path.

func (*PathItemV31) MarshalJSON 

func (p *PathItemV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for PathItemV31 to inline extensions.

type RequestBodyV30 

type RequestBodyV30 struct {
	Ref         string                   `json:"$ref,omitempty"`
	Description string                   `json:"description,omitempty"`
	Required    bool                     `json:"required,omitempty"`
	Content     map[string]*MediaTypeV30 `json:"content,omitempty"`
	Extensions  map[string]any           `json:"-"`
}

RequestBodyV30 describes a single request body.

func (*RequestBodyV30) MarshalJSON 

func (r *RequestBodyV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for RequestBodyV30 to inline extensions.

type RequestBodyV31 

type RequestBodyV31 struct {
	Ref         string                   `json:"$ref,omitempty"`
	Description string                   `json:"description,omitempty"`
	Required    bool                     `json:"required,omitempty"`
	Content     map[string]*MediaTypeV31 `json:"content,omitempty"`
	Extensions  map[string]any           `json:"-"`
}

RequestBodyV31 describes a request body.

func (*RequestBodyV31) MarshalJSON 

func (r *RequestBodyV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for RequestBodyV31 to inline extensions.

type ReservedExtensionKeyError 

type ReservedExtensionKeyError struct {
	Key string
}

ReservedExtensionKeyError indicates an extension key uses a reserved prefix.

func (*ReservedExtensionKeyError) Error 

func (e *ReservedExtensionKeyError) Error() string

func (*ReservedExtensionKeyError) Unwrap 

func (e *ReservedExtensionKeyError) Unwrap() error

Unwrap returns nil as ReservedExtensionKeyError is a leaf error type. This allows errors.Is() and errors.As() to work correctly.

type ResponseV30 

type ResponseV30 struct {
	Ref         string                   `json:"$ref,omitempty"`
	Description string                   `json:"description,omitempty"`
	Content     map[string]*MediaTypeV30 `json:"content,omitempty"`
	Headers     map[string]*HeaderV30    `json:"headers,omitempty"`
	Links       map[string]*LinkV30      `json:"links,omitempty"`
	Extensions  map[string]any           `json:"-"`
}

ResponseV30 describes a single response.

func (*ResponseV30) MarshalJSON 

func (r *ResponseV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ResponseV30 to inline extensions.

type ResponseV31 

type ResponseV31 struct {
	Ref         string                   `json:"$ref,omitempty"`
	Description string                   `json:"description,omitempty"`
	Content     map[string]*MediaTypeV31 `json:"content,omitempty"`
	Headers     map[string]*HeaderV31    `json:"headers,omitempty"`
	Links       map[string]*LinkV31      `json:"links,omitempty"`
	Extensions  map[string]any           `json:"-"`
}

ResponseV31 describes a response.

func (*ResponseV31) MarshalJSON 

func (r *ResponseV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ResponseV31 to inline extensions.

type Result 

type Result struct {
	// JSON is the marshaled OpenAPI specification as JSON bytes.
	JSON []byte

	// YAML is the marshaled OpenAPI specification as YAML bytes.
	YAML []byte

	// Warnings contains any warnings generated during projection.
	// Warnings are generated when 3.1-only features are used with a 3.0 target.
	Warnings diag.Warnings
}

Result contains the output of spec projection.

func Project 

func Project(ctx context.Context, spec *model.Spec, cfg Config) (Result, error)

Project converts the internal model.Spec (IR) to a version-specific OpenAPI JSON and YAML specification (3.0.4 or 3.1.2).

This function handles version-specific differences:

  • Schema definitions (nullable vs type union, exclusive bounds)
  • Keywords (const support, webhooks, mutualTLS)
  • Reserved extension prefixes (x-oai-, x-oas- in 3.1.x)

Features that exist only in 3.1.x are either:

  • Dropped with warnings when projecting to 3.0.4
  • Cause errors if StrictDownlevel is enabled

The returned Result contains the marshaled JSON/YAML and any warnings generated during projection (e.g., info.summary dropped, license.identifier dropped).

If a Validator is provided in cfg, the generated specification is validated against the appropriate OpenAPI meta-schema before returning.

type SchemaV30 

type SchemaV30 struct {
	Ref              string                `json:"$ref,omitempty"`
	Title            string                `json:"title,omitempty"`
	Type             string                `json:"type,omitempty"`
	Format           string                `json:"format,omitempty"`
	Description      string                `json:"description,omitempty"`
	Example          any                   `json:"example,omitempty"`
	Deprecated       bool                  `json:"deprecated,omitempty"`
	ReadOnly         bool                  `json:"readOnly,omitempty"`
	WriteOnly        bool                  `json:"writeOnly,omitempty"`
	Nullable         bool                  `json:"nullable,omitempty"`
	Discriminator    *DiscriminatorV30     `json:"discriminator,omitempty"`
	XML              *XMLV30               `json:"xml,omitempty"`
	Enum             []any                 `json:"enum,omitempty"`
	MultipleOf       *float64              `json:"multipleOf,omitempty"`
	Maximum          *float64              `json:"maximum,omitempty"`
	ExclusiveMaximum *bool                 `json:"exclusiveMaximum,omitempty"`
	Minimum          *float64              `json:"minimum,omitempty"`
	ExclusiveMinimum *bool                 `json:"exclusiveMinimum,omitempty"`
	Pattern          string                `json:"pattern,omitempty"`
	MaxLength        *int                  `json:"maxLength,omitempty"`
	MinLength        *int                  `json:"minLength,omitempty"`
	Items            *SchemaV30            `json:"items,omitempty"`
	MaxItems         *int                  `json:"maxItems,omitempty"`
	MinItems         *int                  `json:"minItems,omitempty"`
	UniqueItems      bool                  `json:"uniqueItems,omitempty"`
	Properties       map[string]*SchemaV30 `json:"properties,omitempty"`
	Required         []string              `json:"required,omitempty"`
	AdditionalProps  any                   `json:"additionalProperties,omitempty"` // bool or *SchemaV30
	AllOf            []*SchemaV30          `json:"allOf,omitempty"`
	AnyOf            []*SchemaV30          `json:"anyOf,omitempty"`
	OneOf            []*SchemaV30          `json:"oneOf,omitempty"`
	Not              *SchemaV30            `json:"not,omitempty"`
	Default          any                   `json:"default,omitempty"`
	Extensions       map[string]any        `json:"-"`
}

SchemaV30 represents an OpenAPI 3.0.4 schema.

func (*SchemaV30) MarshalJSON 

func (s *SchemaV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SchemaV30 to inline extensions.

type SchemaV31 

type SchemaV31 struct {
	Ref               string                `json:"$ref,omitempty"`
	Title             string                `json:"title,omitempty"`
	Type              any                   `json:"type,omitempty"` // string or []string
	Format            string                `json:"format,omitempty"`
	ContentEncoding   string                `json:"contentEncoding,omitempty"`
	ContentMediaType  string                `json:"contentMediaType,omitempty"`
	Description       string                `json:"description,omitempty"`
	Example           any                   `json:"example,omitempty"`
	Examples          []any                 `json:"examples,omitempty"`
	Deprecated        bool                  `json:"deprecated,omitempty"`
	ReadOnly          bool                  `json:"readOnly,omitempty"`
	WriteOnly         bool                  `json:"writeOnly,omitempty"`
	Discriminator     *DiscriminatorV31     `json:"discriminator,omitempty"`
	XML               *XMLV31               `json:"xml,omitempty"`
	Enum              []any                 `json:"enum,omitempty"`
	Const             any                   `json:"const,omitempty"`
	MultipleOf        *float64              `json:"multipleOf,omitempty"`
	Maximum           *float64              `json:"maximum,omitempty"`
	ExclusiveMaximum  *float64              `json:"exclusiveMaximum,omitempty"`
	Minimum           *float64              `json:"minimum,omitempty"`
	ExclusiveMinimum  *float64              `json:"exclusiveMinimum,omitempty"`
	Pattern           string                `json:"pattern,omitempty"`
	MaxLength         *int                  `json:"maxLength,omitempty"`
	MinLength         *int                  `json:"minLength,omitempty"`
	Items             *SchemaV31            `json:"items,omitempty"`
	MaxItems          *int                  `json:"maxItems,omitempty"`
	MinItems          *int                  `json:"minItems,omitempty"`
	UniqueItems       bool                  `json:"uniqueItems,omitempty"`
	Properties        map[string]*SchemaV31 `json:"properties,omitempty"`
	Required          []string              `json:"required,omitempty"`
	AdditionalProps   any                   `json:"additionalProperties,omitempty"` // bool or *SchemaV31
	PatternProperties map[string]*SchemaV31 `json:"patternProperties,omitempty"`
	UnevaluatedProps  *SchemaV31            `json:"unevaluatedProperties,omitempty"`
	AllOf             []*SchemaV31          `json:"allOf,omitempty"`
	AnyOf             []*SchemaV31          `json:"anyOf,omitempty"`
	OneOf             []*SchemaV31          `json:"oneOf,omitempty"`
	Not               *SchemaV31            `json:"not,omitempty"`
	Default           any                   `json:"default,omitempty"`
	MinProperties     *int                  `json:"minProperties,omitempty"`
	MaxProperties     *int                  `json:"maxProperties,omitempty"`
	Extensions        map[string]any        `json:"-"`
}

SchemaV31 represents an OpenAPI 3.1.x schema.

func (*SchemaV31) MarshalJSON 

func (s *SchemaV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SchemaV31 to inline extensions.

type SecurityRequirementV30 

type SecurityRequirementV30 map[string][]string

SecurityRequirementV30 lists the required security schemes for an operation.

type SecurityRequirementV31 

type SecurityRequirementV31 map[string][]string

SecurityRequirementV31 lists required security schemes.

type SecuritySchemeV30 

type SecuritySchemeV30 struct {
	Ref              string         `json:"$ref,omitempty"`
	Type             string         `json:"type,omitempty"`
	Description      string         `json:"description,omitempty"`
	Name             string         `json:"name,omitempty"`
	In               string         `json:"in,omitempty"`
	Scheme           string         `json:"scheme,omitempty"`
	BearerFormat     string         `json:"bearerFormat,omitempty"`
	Flows            *OAuthFlowsV30 `json:"flows,omitempty"`
	OpenIDConnectURL string         `json:"openIdConnectUrl,omitempty"`
	Extensions       map[string]any `json:"-"`
}

SecuritySchemeV30 defines a security scheme.

func (*SecuritySchemeV30) MarshalJSON 

func (s *SecuritySchemeV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SecuritySchemeV30 to inline extensions.

type SecuritySchemeV31 

type SecuritySchemeV31 struct {
	Ref              string         `json:"$ref,omitempty"`
	Type             string         `json:"type,omitempty"`
	Description      string         `json:"description,omitempty"`
	Name             string         `json:"name,omitempty"`
	In               string         `json:"in,omitempty"`
	Scheme           string         `json:"scheme,omitempty"`
	BearerFormat     string         `json:"bearerFormat,omitempty"`
	Flows            *OAuthFlowsV31 `json:"flows,omitempty"`
	OpenIDConnectURL string         `json:"openIdConnectUrl,omitempty"`
	Extensions       map[string]any `json:"-"`
}

SecuritySchemeV31 defines a security scheme.

func (*SecuritySchemeV31) MarshalJSON 

func (s *SecuritySchemeV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SecuritySchemeV31 to inline extensions.

type ServerV30 

type ServerV30 struct {
	URL         string                        `json:"url"`
	Description string                        `json:"description,omitempty"`
	Variables   map[string]*ServerVariableV30 `json:"variables,omitempty"`
	Extensions  map[string]any                `json:"-"`
}

ServerV30 represents a server URL.

func (*ServerV30) MarshalJSON 

func (s *ServerV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ServerV30 to inline extensions.

type ServerV31 

type ServerV31 struct {
	URL         string                        `json:"url"`
	Description string                        `json:"description,omitempty"`
	Variables   map[string]*ServerVariableV31 `json:"variables,omitempty"`
	Extensions  map[string]any                `json:"-"`
}

ServerV31 represents a server URL.

func (*ServerV31) MarshalJSON 

func (s *ServerV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ServerV31 to inline extensions.

type ServerVariableV30 

type ServerVariableV30 struct {
	Enum        []string       `json:"enum,omitempty"`        // Enumeration of allowed values (SHOULD NOT be empty)
	Default     string         `json:"default"`               // REQUIRED. Default value for substitution
	Description string         `json:"description,omitempty"` // Optional description
	Extensions  map[string]any `json:"-"`
}

ServerVariableV30 represents a server variable for URL template substitution.

func (*ServerVariableV30) MarshalJSON 

func (s *ServerVariableV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ServerVariableV30 to inline extensions.

type ServerVariableV31 

type ServerVariableV31 struct {
	Enum        []string       `json:"enum,omitempty"`        // Enumeration of allowed values (MUST NOT be empty)
	Default     string         `json:"default"`               // REQUIRED. Default value for substitution
	Description string         `json:"description,omitempty"` // Optional description
	Extensions  map[string]any `json:"-"`
}

ServerVariableV31 represents a server variable for URL template substitution.

func (*ServerVariableV31) MarshalJSON 

func (s *ServerVariableV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ServerVariableV31 to inline extensions.

type SpecV30 

type SpecV30 struct {
	OpenAPI string `json:"openapi"`
	// Info is a pointer to ensure custom MarshalJSON methods are invoked
	// for nested structs when the parent struct uses type aliases to avoid
	// infinite recursion in MarshalJSON implementations.
	Info         *InfoV30                 `json:"info"`
	Servers      []ServerV30              `json:"servers,omitempty"`
	Paths        map[string]*PathItemV30  `json:"paths"`
	Components   *ComponentsV30           `json:"components,omitempty"`
	Tags         []TagV30                 `json:"tags,omitempty"`
	Security     []SecurityRequirementV30 `json:"security,omitempty"`
	ExternalDocs *ExternalDocsV30         `json:"externalDocs,omitempty"`
	Extensions   map[string]any           `json:"-"`
}

SpecV30 represents an OpenAPI 3.0.4 specification. This type is defined here to avoid import cycles with the openapi package.

func (*SpecV30) MarshalJSON 

func (s *SpecV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SpecV30 to inline extensions.

type SpecV31 

type SpecV31 struct {
	OpenAPI           string `json:"openapi"`
	JSONSchemaDialect string `json:"jsonSchemaDialect,omitempty"`
	// Info is a pointer to ensure custom MarshalJSON methods are invoked
	// for nested structs when the parent struct uses type aliases to avoid
	// infinite recursion in MarshalJSON implementations.
	Info         *InfoV31                 `json:"info"`
	Servers      []ServerV31              `json:"servers,omitempty"`
	Paths        map[string]*PathItemV31  `json:"paths,omitempty"`
	Components   *ComponentsV31           `json:"components,omitempty"`
	Webhooks     map[string]*PathItemV31  `json:"webhooks,omitempty"`
	Tags         []TagV31                 `json:"tags,omitempty"`
	Security     []SecurityRequirementV31 `json:"security,omitempty"`
	ExternalDocs *ExternalDocsV31         `json:"externalDocs,omitempty"`
	Extensions   map[string]any           `json:"-"`
}

SpecV31 represents an OpenAPI 3.1.x specification.

func (*SpecV31) MarshalJSON 

func (s *SpecV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SpecV31 to inline extensions.

type TagV30 

type TagV30 struct {
	Name         string           `json:"name"`
	Description  string           `json:"description,omitempty"`
	ExternalDocs *ExternalDocsV30 `json:"externalDocs,omitempty"`
	Extensions   map[string]any   `json:"-"`
}

TagV30 adds metadata to a single tag.

func (*TagV30) MarshalJSON 

func (t *TagV30) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for TagV30 to inline extensions.

type TagV31 

type TagV31 struct {
	Name         string           `json:"name"`
	Description  string           `json:"description,omitempty"`
	ExternalDocs *ExternalDocsV31 `json:"externalDocs,omitempty"`
	Extensions   map[string]any   `json:"-"`
}

TagV31 adds metadata to a tag.

func (*TagV31) MarshalJSON 

func (t *TagV31) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for TagV31 to inline extensions.

type Validator 

type Validator interface {
	// Validate validates an OpenAPI specification JSON against its meta-schema.
	Validate(ctx context.Context, specJSON []byte, version validate.Version) error
}

Validator validates generated OpenAPI specifications.

type Version 

type Version string

Version represents an OpenAPI specification version. 

const (
	// V30 represents OpenAPI 3.0.4.
	V30 Version = "3.0.4"
	// V31 represents OpenAPI 3.1.2.
	V31 Version = "3.1.2"
)

type XMLV30 

type XMLV30 struct {
	Name      string `json:"name,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Attribute bool   `json:"attribute,omitempty"`
	Wrapped   bool   `json:"wrapped,omitempty"`
}

XMLV30 provides XML serialization hints.

type XMLV31 

type XMLV31 struct {
	Name      string `json:"name,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Attribute bool   `json:"attribute,omitempty"`
	Wrapped   bool   `json:"wrapped,omitempty"`
}

XMLV31 provides XML serialization hints.

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.