spec

type Contact struct {
	Name  string
	URL   string
	Email string
}

type Info struct {
	Title          string
	Version        string
	Description    string
	TermsOfService string
	Contact        *Contact
	License        *License
}

type License struct {
	Name string
	URL  string
}

type NamedSecurityScheme struct {
	Name   string
	Scheme SecurityScheme
}

type OAuthFlow struct {
	AuthorizationURL string
	TokenURL         string
	RefreshURL       string
	// DeviceAuthorizationURL is required for (and only meaningful
	// on) the OpenAPI 3.2 deviceAuthorization flow.
	DeviceAuthorizationURL string
	Scopes                 map[string]string
}

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow
	AuthorizationCode *OAuthFlow
	// DeviceAuthorization is the RFC 8628 device flow added in
	// OpenAPI 3.2. It is emitted for every version (3.0/3.1
	// validators will flag it), so only set it on a 3.2 mux. Its
	// flow object requires DeviceAuthorizationURL and TokenURL.
	DeviceAuthorization *OAuthFlow
}

type Operation struct {
	Method      string
	Summary     string
	Description string
	Tags        []string
	OperationID string
	Deprecated  bool
	Parameters  []Param
	RequestBody *RequestBody
	Responses   map[string]*Response // status -> response
	// Security is the list of security requirements for this
	// operation. Each requirement is a map of scheme name to scopes.
	// An empty Security slice means "use the global security"; to
	// opt out of auth on a specific route, set NoSecurity to true
	// (which emits an empty `security: []` array — required by the
	// OpenAPI spec to override a globally-applied scheme).
	Security []SecurityRequirement
	// NoSecurity, when true, emits an empty `security` array on
	// this operation, overriding any global security requirement.
	// See WithNoSecurity in the root package.
	NoSecurity bool
	// Hidden, when true, excludes the operation from the generated
	// document unconditionally. See Hidden in the root package.
	Hidden bool
	// Internal, when true, excludes the operation from the generated
	// document unless the mux policy shows internal routes
	// (WithInternal(true)); when shown, the operation carries an
	// "x-internal": true extension. See Internal in the root package.
	Internal bool
	// ResponseOrder tracks the order in which responses were added
	// to the Responses map. Used by WithExample to pick the
	// "most recent" response when no explicit status is given.
	ResponseOrder []string
	// Extensions is a map of x-* extension fields. These are
	// emitted directly onto the operation object. The reflector
	// uses this to surface warnings about non-standard method
	// names, custom status codes, etc. The map is never modified
	// by the emitter.
	Extensions map[string]any
}

type Param struct {
	Name        string
	In          string // "path", "query", "header", "cookie"
	Required    bool
	Description string
	Schema      *schema.Schema
}

type PathItem struct {
	Path       string
	Operations map[string]*Operation // method -> operation
	Parameters []Param               // path-level, shared across methods
}

type RequestBody struct {
	Description string
	Required    bool
	Schema      *schema.Schema
	ContentType string // defaults to "application/json"
	// Example is the JSON-serialised example value (set via
	// WithExample). nil means no example is set.
	Example any
	// BodyValue is the original Go value passed to WithBody. Used
	// internally to re-derive component schemas at spec-build time.
	BodyValue any
}

type Response struct {
	Status      string // e.g. "200", "404", "default"
	Description string
	Schema      *schema.Schema // optional body schema
	Headers     map[string]*schema.Schema
	// Example is the JSON-serialised example value for this response
	// (set via WithExample or WithResponseExample). nil means no
	// example is set. It is not serialized into the spec; the
	// emitter reads it from a parallel field.
	Example any
	// BodyValue is the original Go value passed to WithResponse. It is
	// used internally to re-derive component schemas at spec-build
	// time. It is not serialized into the spec.
	BodyValue any
}

type SecurityRequirement map[string][]string

type SecurityScheme struct {
	Type             SecuritySchemeType
	Description      string
	Name             string // for apiKey: the parameter name
	In               string // for apiKey: "header" | "query" | "cookie"
	Scheme           string // for http: "bearer" | "basic" | ...
	BearerFormat     string // for http bearer: e.g. "JWT"
	Flows            *OAuthFlows
	OpenIDConnectURL string
}

type SecuritySchemeType string

type Server struct {
	URL         string
	Description string
}

type SpecInput struct {
	Info            Info
	Servers         []Server
	Tags            []TagDecl
	Paths           []PathItem
	Components      map[string]*schema.Schema
	Version         version.SpecVersion
	SecuritySchemes []NamedSecurityScheme
	GlobalSecurity  []SecurityRequirement
	Webhooks        map[string]Webhook
}

type TagDecl struct {
	Name        string
	Description string
}

type Webhook struct {
	// Method is the HTTP method (POST, GET, etc.) used to deliver
	// the webhook payload. Required.
	Method string
	// Summary is a short description.
	Summary string
	// Description is a long description (Markdown).
	Description string
	// OperationID identifies the webhook uniquely within the API.
	OperationID string
	// RequestBody is the payload structure (optional).
	RequestBody *RequestBody
	// Responses lists expected responses (e.g. 200, 202).
	Responses map[string]*Response
}