/**
 * OpenAPI operation-level metadata for HTTP contracts.
 */

/**
 * Inline OpenAPI schema metadata or a `$ref` to a schema component.
 */
export type OpenAPISchemaMeta = Record<string, unknown> | { $ref: string };

/**
 * OpenAPI media type metadata for request and response content entries.
 */
export type OpenAPIMediaTypeMeta = {
  schema?: OpenAPISchemaMeta;
  examples?: Record<
    string,
    {
      summary?: string;
      value?: unknown;
    }
  >;
};

/**
 * OpenAPI request body metadata used to override generated JSON request bodies.
 */
export type OpenAPIRequestBodyMeta = {
  required?: boolean;
  description?: string;
  content: Record<string, OpenAPIMediaTypeMeta>;
};

/**
 * OpenAPI response metadata used to add or replace generated responses.
 */
export type OpenAPIResponseMeta = {
  description: string;
  content?: Record<string, OpenAPIMediaTypeMeta>;
};

/**
 * OpenAPI operation parameter metadata used for custom parameters such as cookies.
 */
export type OpenAPIParameterMeta = {
  name: string;
  in: "path" | "query" | "header" | "cookie";
  required?: boolean;
  schema?: OpenAPISchemaMeta;
  description?: string;
  deprecated?: boolean;
};

export type OpenAPIOperationMeta = {
  /** Brief operation summary. */
  summary?: string;
  /** Detailed operation description. */
  description?: string;
  /** Tags used to group operations. */
  tags?: string[];
  /** Whether the operation is deprecated. */
  deprecated?: boolean;
  /** External documentation reference. */
  externalDocs?: {
    description?: string;
    url: string;
  };
  /** Operation ID override. Defaults to `contract.name`. */
  operationId?: string;
  /** Per-operation security requirements. */
  security?: Array<Record<string, string[]>>;
  /** Additional or replacement operation parameters. */
  parameters?: OpenAPIParameterMeta[];
  /** Replacement request body for non-JSON media such as multipart uploads. */
  requestBody?: OpenAPIRequestBodyMeta;
  /** Additional or replacement responses, useful for files and streams. */
  responses?: Record<string, OpenAPIResponseMeta>;
};