spec

type Catalog struct {
	Commands []*Command
}

type Command struct {
	Key         string // METHOD /path
	Method      string
	Path        string
	Summary     string
	Description string

	PathParts   []string
	Aliases     []string
	Risk        Risk
	Internal    bool
	Async       string
	OperateType string
	Examples    []string

	Flags []*Flag
	// ComplexRequired lists required body fields that cannot be a flag
	// (arrays of objects / nested objects); they must be supplied via --json.
	ComplexRequired []string

	Body           *Schema
	BodySchemaName string
}

type CommandOverride struct {
	Op          string   `yaml:"op"`
	Path        []string `yaml:"path"`
	Aliases     []string `yaml:"aliases,omitempty"`
	Risk        string   `yaml:"risk,omitempty"`
	Internal    bool     `yaml:"internal,omitempty"`
	Async       string   `yaml:"async,omitempty"`
	OperateType string   `yaml:"operate_type,omitempty"`
	Examples    []string `yaml:"examples,omitempty"`
}

type Components struct {
	Schemas map[string]*Schema `yaml:"schemas"`
}

type Document struct {
	OpenAPI    string                           `yaml:"openapi"`
	Info       Info                             `yaml:"info"`
	Paths      map[string]map[string]*Operation `yaml:"paths"`
	Components Components                       `yaml:"components"`
}

type Flag struct {
	Name        string // kebab-case CLI name, without --
	Field       string // JSON / query field name
	In          string // query, path, or body
	Type        string
	Description string
	Required    bool
	Enum        []any
	Default     any
}

type Info struct {
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Version     string `yaml:"version"`
}

type MediaType struct {
	Schema *Schema `yaml:"schema"`
}

type Operation struct {
	Summary     string              `yaml:"summary"`
	Description string              `yaml:"description"`
	Tags        []string            `yaml:"tags"`
	Parameters  []Parameter         `yaml:"parameters"`
	RequestBody *RequestBody        `yaml:"requestBody"`
	Responses   map[string]Response `yaml:"responses"`
	Deprecated  bool                `yaml:"deprecated"`
}

type OperationRef struct {
	Method string
	Path   string
	Op     *Operation
}

type Overlay struct {
	Commands []CommandOverride `yaml:"commands"`
}

type Parameter struct {
	Name        string  `yaml:"name"`
	In          string  `yaml:"in"`
	Description string  `yaml:"description"`
	Required    bool    `yaml:"required"`
	Schema      *Schema `yaml:"schema"`
}

type RequestBody struct {
	Required bool                 `yaml:"required"`
	Content  map[string]MediaType `yaml:"content"`
}

type Response struct {
	Description string               `yaml:"description"`
	Content     map[string]MediaType `yaml:"content"`
}

type Risk string

type Schema struct {
	Ref         string             `yaml:"$ref"`
	Type        string             `yaml:"type"`
	Format      string             `yaml:"format"`
	Description string             `yaml:"description"`
	Required    []string           `yaml:"required"`
	Properties  map[string]*Schema `yaml:"properties"`
	Items       *Schema            `yaml:"items"`
	Enum        []any              `yaml:"enum"`
	Example     any                `yaml:"example"`
	Default     any                `yaml:"default"`
	Nullable    bool               `yaml:"nullable"`
}