OpenAPI 3.1 Types

/**
 * Root OpenAPI 3.1 document structure
 * @template T - Extension object type for custom properties
 */
type Document<T extends {} = {}> = {
  openapi: string;
  info: InfoObject;
  jsonSchemaDialect?: string;
  servers?: ServerObject[];
} & (
  | { paths: PathsObject<T>; webhooks?: Record<string, PathItemObject | ReferenceObject>; components?: ComponentsObject; }
  | { webhooks: Record<string, PathItemObject | ReferenceObject>; paths?: PathsObject<T>; components?: ComponentsObject; }
  | { components: ComponentsObject; paths?: PathsObject<T>; webhooks?: Record<string, PathItemObject | ReferenceObject>; }
);

/**
 * Enhanced API information object for OpenAPI 3.1 
 */
type InfoObject = {
  title: string;
  summary?: string;
  description?: string;
  termsOfService?: string;
  contact?: ContactObject;
  license?: LicenseObject;
  version: string;
};

/**
 * Contact information object
 */
type ContactObject = {
  name?: string;
  url?: string;
  email?: string;
};

/**
 * License information object with identifier support
 */
type LicenseObject = {
  name: string;
  identifier?: string;
  url?: string;
};

/**
 * Server configuration object
 */
type ServerObject = {
  url: string;
  description?: string;
  variables?: Record<string, ServerVariableObject>;
};

/**
 * Server variable object with enhanced enum support
 */
type ServerVariableObject = {
  enum?: [string, ...string[]];
  default: string;
  description?: string;
};

/**
 * Collection of API paths
 * @template T - Extension object type for custom properties
 * @template P - Path-level extension object type
 */
type PathsObject<T extends {} = {}, P extends {} = {}> = Record<
  string,
  (PathItemObject<T> & P) | undefined
>;

/**
 * Path item object with operation definitions
 * @template T - Extension object type for custom properties
 */
type PathItemObject<T extends {} = {}> = {
  $ref?: string;
  summary?: string;
  description?: string;
  servers?: ServerObject[];
  parameters?: (ReferenceObject | ParameterObject)[];
  get?: OperationObject<T>;
  put?: OperationObject<T>;
  post?: OperationObject<T>;
  delete?: OperationObject<T>;
  options?: OperationObject<T>;
  head?: OperationObject<T>;
  patch?: OperationObject<T>;
  trace?: OperationObject<T>;
};

/**
 * HTTP operation object
 * @template T - Extension object type for custom properties
 */
type OperationObject<T extends {} = {}> = {
  tags?: string[];
  summary?: string;
  description?: string;
  externalDocs?: ExternalDocumentationObject;
  operationId?: string;
  parameters?: (ReferenceObject | ParameterObject)[];
  requestBody?: ReferenceObject | RequestBodyObject;
  responses?: ResponsesObject;
  callbacks?: Record<string, ReferenceObject | CallbackObject>;
  deprecated?: boolean;
  security?: SecurityRequirementObject[];
  servers?: ServerObject[];
} & T;

/**
 * Enhanced schema object supporting mixed types and JSON Schema 2020-12 features
 */
type SchemaObject = ArraySchemaObject | NonArraySchemaObject | MixedSchemaObject;

/**
 * Array schema object
 */
interface ArraySchemaObject extends BaseSchemaObject {
  type: 'array';
  items: ReferenceObject | SchemaObject;
}

/**
 * Non-array schema object with null support
 */
interface NonArraySchemaObject extends BaseSchemaObject {
  type?: 'boolean' | 'object' | 'number' | 'string' | 'integer' | 'null';
}

/**
 * Mixed schema object supporting multiple types
 */
interface MixedSchemaObject extends BaseSchemaObject {
  type?: ('array' | 'boolean' | 'object' | 'number' | 'string' | 'integer' | 'null')[];
  items?: ReferenceObject | SchemaObject;
}

/**
 * Base schema object with JSON Schema 2020-12 features
 */
type BaseSchemaObject = {
  title?: string;
  description?: string;
  format?: string;
  default?: any;
  multipleOf?: number;
  maximum?: number;
  exclusiveMaximum?: boolean | number;
  minimum?: number;
  exclusiveMinimum?: boolean | number;
  maxLength?: number;
  minLength?: number;
  pattern?: string;
  maxItems?: number;
  minItems?: number;
  uniqueItems?: boolean;
  maxProperties?: number;
  minProperties?: number;
  required?: string[];
  enum?: any[];
  const?: any;
  examples?: any[];
  contentMediaType?: string;
  $schema?: string;
  additionalProperties?: boolean | ReferenceObject | SchemaObject;
  properties?: { [name: string]: ReferenceObject | SchemaObject };
  allOf?: (ReferenceObject | SchemaObject)[];
  oneOf?: (ReferenceObject | SchemaObject)[];
  anyOf?: (ReferenceObject | SchemaObject)[];
  not?: ReferenceObject | SchemaObject;
  discriminator?: DiscriminatorObject;
  readOnly?: boolean;
  writeOnly?: boolean;
  xml?: XMLObject;
  externalDocs?: ExternalDocumentationObject;
  example?: any;
  deprecated?: boolean;
};

/**
 * Enhanced reference object with summary and description
 */
type ReferenceObject = {
  $ref: string;
  summary?: string;
  description?: string;
};

/**
 * Request body object
 */
type RequestBodyObject = {
  description?: string;
  content: { [media: string]: MediaTypeObject };
  required?: boolean;
};

/**
 * Collection of response objects
 */
type ResponsesObject = Record<string, ReferenceObject | ResponseObject>;

/**
 * Response object definition
 */
type ResponseObject = {
  description: string;
  headers?: { [header: string]: ReferenceObject | HeaderObject };
  content?: { [media: string]: MediaTypeObject };
  links?: { [link: string]: ReferenceObject | LinkObject };
};

/**
 * Media type object with schema and examples
 */
type MediaTypeObject = {
  schema?: SchemaObject | ReferenceObject;
  example?: any;
  examples?: Record<string, ReferenceObject | ExampleObject>;
  encoding?: { [media: string]: EncodingObject };
};

/**
 * Reusable components object
 */
type ComponentsObject = {
  schemas?: Record<string, SchemaObject>;
  responses?: Record<string, ReferenceObject | ResponseObject>;
  parameters?: Record<string, ReferenceObject | ParameterObject>;
  examples?: Record<string, ReferenceObject | ExampleObject>;
  requestBodies?: Record<string, ReferenceObject | RequestBodyObject>;
  headers?: Record<string, ReferenceObject | HeaderObject>;
  securitySchemes?: Record<string, ReferenceObject | SecuritySchemeObject>;
  links?: Record<string, ReferenceObject | LinkObject>;
  callbacks?: Record<string, ReferenceObject | CallbackObject>;
  pathItems?: Record<string, ReferenceObject | PathItemObject>;
};

import { OpenAPIV3_1 } from "openapi-types";

// OpenAPI 3.1 document with webhooks
const apiDoc: OpenAPIV3_1.Document = {
  openapi: "3.1.0",
  info: {
    title: "Webhook API",
    version: "1.0.0",
    summary: "API with webhook support"
  },
  jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema",
  webhooks: {
    newUser: {
      post: {
        requestBody: {
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  userId: { type: "string" },
                  email: { type: "string" }
                }
              }
            }
          }
        },
        responses: {
          "200": {
            description: "Webhook received"
          }
        }
      }
    }
  }
};

// Using enhanced schema features
const enhancedSchema: OpenAPIV3_1.SchemaObject = {
  type: ["string", "null"],
  examples: ["example1", "example2", null],
  const: "constant_value"
};

// Enhanced reference with description
const enhancedRef: OpenAPIV3_1.ReferenceObject = {
  $ref: "#/components/schemas/User",
  summary: "User reference",
  description: "Reference to the User schema"
};