openapi

type API struct {
	Version    Version
	Tags       []Tag
	Servers    []Server
	Operations []*Operation
	Webhooks   []Webhook
	Components *Components
	Info       Info
}

type Components struct {
	Schemas       map[string]*jsonschema.Schema
	Responses     map[string]*Response
	Parameters    map[string]*Parameter
	Examples      map[string]*Example
	RequestBodies map[string]*RequestBody
}

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.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// The email address of the contact person/organization.
	Email string `json:"email,omitempty" yaml:"email,omitempty"`

	// Specification extensions.
	Extensions Extensions `json:"-" yaml:",inline"`
}

type Encoding struct {
	ContentType   string
	Headers       map[string]*Header
	Style         ParameterStyle
	Explode       bool
	AllowReserved bool

	location.Pointer `json:"-" yaml:"-"`
}

type Example struct {
	Ref Ref

	Summary       string
	Description   string
	Value         jsonschema.Example
	ExternalValue string

	location.Pointer `json:"-" yaml:"-"`
}

type Extensions = jsonschema.Extensions

type Header = Parameter

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 short 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. MUST be in the format of a URL.
	TermsOfService string `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
	// The contact information for the exposed API.
	Contact *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	// The license information for the exposed API.
	License *License `json:"license,omitempty" yaml:"license,omitempty"`
	// REQUIRED. The version of the OpenAPI document.
	Version string `json:"version" yaml:"version"`

	// Specification extensions.
	Extensions Extensions `json:"-" yaml:",inline"`
}

type License struct {
	// REQUIRED. The license name used for the API.
	Name string `json:"name" yaml:"name"`
	// An SPDX license expression for the API.
	Identifier string `json:"identifier,omitempty" yaml:"identifier,omitempty"`
	// A URL to the license used for the API.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// Specification extensions.
	Extensions Extensions `json:"-" yaml:",inline"`
}

type MediaType struct {
	Schema   *jsonschema.Schema
	Example  json.RawMessage
	Examples map[string]*Example
	Encoding map[string]*Encoding

	XOgenJSONStreaming bool
	XOgenRawResponse   bool

	location.Pointer `json:"-" yaml:"-"`
}

type OAuthFlow struct {
	AuthorizationURL string
	TokenURL         string
	RefreshURL       string
	Scopes           map[string]string // name -> description

	location.Pointer `json:"-" yaml:"-"`
}

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow
	AuthorizationCode *OAuthFlow

	location.Pointer `json:"-" yaml:"-"`
}

type Operation struct {
	Tags        []string // optional
	OperationID string   // optional
	Summary     string   // optional
	Description string   // optional
	Deprecated  bool     // optional

	HTTPMethod  string
	Path        Path
	Parameters  []*Parameter
	RequestBody *RequestBody // optional

	// Security requirements.
	Security SecurityRequirements

	// Operation responses.
	Responses Responses

	XOgenOperationGroup string // Extension field for operation grouping.

	location.Pointer `json:"-" yaml:"-"`
}

type Parameter struct {
	Ref Ref

	Name          string
	Description   string
	Deprecated    bool
	Schema        *jsonschema.Schema
	Content       *ParameterContent
	In            ParameterLocation
	Style         ParameterStyle
	Explode       bool
	Required      bool
	AllowReserved bool

	// XOgenName is the custom Go field name specified by x-ogen-name extension.
	XOgenName string

	location.Pointer `json:"-" yaml:"-"`
}

type ParameterContent struct {
	Name  string
	Media *MediaType
}

type ParameterLocation string

type ParameterStyle string

type Path []PathPart[*Parameter]

type PathPart[P any] struct {
	Raw   string
	Param P
}

type Ref = jsonpointer.RefKey

type RequestBody struct {
	Ref         Ref
	Description string
	Required    bool
	Content     map[string]*MediaType

	location.Pointer `json:"-" yaml:"-"`
}

type Response struct {
	Ref         Ref
	Description string
	Headers     map[string]*Header
	Content     map[string]*MediaType

	location.Pointer `json:"-" yaml:"-"`
}

type Responses struct {
	StatusCode map[int]*Response
	Pattern    [5]*Response
	Default    *Response

	location.Pointer `json:"-" yaml:"-"`
}

type Security struct {
	Type             string
	Description      string
	Name             string
	In               string
	Scheme           string
	BearerFormat     string
	Flows            OAuthFlows
	OpenIDConnectURL string

	XOgenCustomSecurity bool

	location.Pointer `json:"-" yaml:"-"`
}

type SecurityRequirement struct {
	// Each element needs to be satisfied to authorize the request.
	Schemes []SecurityScheme

	location.Pointer `json:"-" yaml:"-"`
}

type SecurityRequirements []SecurityRequirement

type SecurityScheme struct {
	Name     string
	Scopes   []string
	Security Security
}

type Server struct {
	Name        string // optional,extension
	Description string // optional
	Template    ServerURL
}

type ServerURL []PathPart[ServerVariable]

type ServerVariable struct {
	Name        string
	Description string
	Default     string
	Enum        []string
}

type Tag struct {
	Name        string
	Description string
}

type Version struct {
	// Major is the major version number.
	Major int
	// Minor is the minor version number.
	Minor int
	// Patch is the patch version number.
	Patch int
}

type Webhook struct {
	// Name of the webhook.
	Name string
	// Operations of the webhook's Path Item.
	Operations []*Operation

	location.Pointer `json:"-" yaml:"-"`
}