v3

type AnyPolicy struct {
	// Expand turns a jetwarp ANY route into a set of standard methods.
	Expand bool

	// StandardMethods is the expansion set, using request capitalization (typically uppercase).
	// If empty, defaults are used.
	StandardMethods []string

	// Extension adds `x-jetwarp-any: true` on the PathItem when ANY is present.
	Extension bool
}

type Attached struct {
	JSONPath string
	Doc      Document
	JSON     []byte
}

type Config struct {
	Title   string
	Version string

	// JSONPath is where Attach mounts the generated OpenAPI JSON. Default: "/openapi.json".
	JSONPath string

	// Docs controls optional HTML documentation mounting.
	Docs DocsConfig
	Any  AnyPolicy
}

type DiagCode string

type Diagnostic struct {
	Code    DiagCode
	Message string

	// Optional context for tooling.
	Path   string
	Method string
	Seq    uint64
}

type DocsConfig struct {
	// Path is where docs should be mounted (e.g. "/docs").
	// Empty means “don’t mount docs”.
	Path string

	// Provider mounts the docs UI (e.g. Swagger UI).
	// If nil, docs are disabled (even if Path is set; Attach will emit a diagnostic).
	Provider UIProvider

	// Title is the docs page title/branding. If empty, defaults to Config.Title
	// when Provider is non-nil.
	Title string

	// SpecURL overrides the URL the UI should fetch for the OpenAPI JSON.
	// If empty, Attach computes a default from Docs.Path and Config.JSONPath.
	SpecURL string
}

type Document struct {
	OpenAPI string              `json:"openapi"`
	Info    Info                `json:"info"`
	Paths   map[string]PathItem `json:"paths"`
}

type Info struct {
	Title   string `json:"title"`
	Version string `json:"version"`
}

type Operation struct {
	// OperationID is a unique string identifier for the operation.
	// jetwarp derives it deterministically from method + path (see operationID in operation.go).
	OperationID string `json:"operationId,omitempty"`

	// Summary is a short human-readable summary of the operation.
	// Populated by Level 1 annotations; empty at Level 0.
	Summary string `json:"summary,omitempty"`

	// Tags groups operations for tooling (Swagger UI, code generators, etc.).
	// Populated by Level 1 annotations; empty at Level 0.
	Tags []string `json:"tags,omitempty"`

	// Parameters lists path (and eventually query/header) parameters.
	// At Level 0, only path parameters extracted from the route pattern are emitted.
	Parameters []Parameter `json:"parameters,omitempty"`

	Deprecated bool `json:"deprecated,omitempty"`

	// Responses is required by the OAS spec and always emitted.
	// Level 0 emits a single "default" stub; richer schemas are a Level 2 concern.
	Responses map[string]Response `json:"responses"`
}

type Parameter struct {
	Name     string `json:"name"`
	In       string `json:"in"`                 // "path" | "query" | "header" | "cookie"
	Required bool   `json:"required,omitempty"` // path params → always true; query/header → false omitted
	Schema   Schema `json:"schema"`
}

type PathItem struct {
	// Fixed fields — OpenAPI 3.2 includes query alongside the classic set.
	Get     *Operation `json:"get,omitempty"`
	Put     *Operation `json:"put,omitempty"`
	Post    *Operation `json:"post,omitempty"`
	Delete  *Operation `json:"delete,omitempty"`
	Options *Operation `json:"options,omitempty"`
	Head    *Operation `json:"head,omitempty"`
	Patch   *Operation `json:"patch,omitempty"`
	Trace   *Operation `json:"trace,omitempty"`
	Query   *Operation `json:"query,omitempty"`

	// AdditionalOperations holds non-standard verbs.
	// Keys must match request capitalisation and must NOT duplicate fixed-field names.
	// https://spec.openapis.org/oas/v3.2.0#fixed-fields-7
	AdditionalOperations map[string]*Operation `json:"additionalOperations,omitempty"`

	// XjetwarpAny marks paths that originated from a jetwarp ANY route.
	XjetwarpAny bool `json:"x-jetwarp-any,omitempty"`
}

type RegistryRouter interface {
	adapter.Adapter
	adapter.RegistryProvider
}

type Response struct {
	Description string `json:"description"`
}

type Schema struct {
	Type string `json:"type,omitempty"`
}

type UIContext struct {
	// DocsPath is the base mount path for the UI (e.g. "/docs").
	DocsPath string

	// SpecURL is the URL the UI should fetch for the OpenAPI JSON.
	// It may be relative or absolute.
	// If empty, Attach computes a default from DocsPath and Config.JSONPath
	// (see Attach for examples and the compatibility contract).
	SpecURL string

	// Title is a human-facing title for the UI.
	Title string
}

type UIProvider interface {
	Mount(r adapter.Adapter, ctx UIContext) []Diagnostic
}