OpenAPI 3.0 Types

/**
 * Root OpenAPI 3.0 document structure
 * @template T - Extension object type for custom properties
 */
interface Document<T extends {} = {}> {
  openapi: string;
  info: InfoObject;
  servers?: ServerObject[];
  paths: PathsObject<T>;
  components?: ComponentsObject;
  security?: SecurityRequirementObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  'x-express-openapi-additional-middleware'?: (
    | ((request: any, response: any, next: any) => Promise<void>)
    | ((request: any, response: any, next: any) => void)
  )[];
  'x-express-openapi-validation-strict'?: boolean;
}

/**
 * API information object
 */
interface InfoObject {
  title: string;
  description?: string;
  termsOfService?: string;
  contact?: ContactObject;
  license?: LicenseObject;
  version: string;
}

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

/**
 * License information object
 */
interface LicenseObject {
  name: string;
  url?: string;
}

/**
 * External documentation object
 */
interface ExternalDocumentationObject {
  description?: string;
  url: string;
}

/**
 * Tag object for grouping operations
 */
interface TagObject {
  name: string;
  description?: string;
  externalDocs?: ExternalDocumentationObject;
}

/**
 * Server configuration object
 */
interface ServerObject {
  url: string;
  description?: string;
  variables?: { [variable: string]: ServerVariableObject };
}

/**
 * Server variable object
 */
interface ServerVariableObject {
  enum?: string[];
  default: string;
  description?: string;
}

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

/**
 * HTTP methods enumeration
 */
enum HttpMethods {
  GET = 'get',
  PUT = 'put',
  POST = 'post',
  DELETE = 'delete',
  OPTIONS = 'options',
  HEAD = 'head',
  PATCH = 'patch',
  TRACE = 'trace'
}

/**
 * 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)[];
} & {
  [method in HttpMethods]?: 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?: { [callback: string]: ReferenceObject | CallbackObject };
  deprecated?: boolean;
  security?: SecurityRequirementObject[];
  servers?: ServerObject[];
} & T;

/**
 * Parameter object
 */
interface ParameterObject extends ParameterBaseObject {
  name: string;
  in: string;
}

/**
 * Header object
 */
interface HeaderObject extends ParameterBaseObject {}

/**
 * Base parameter object with common properties
 */
interface ParameterBaseObject {
  description?: string;
  required?: boolean;
  deprecated?: boolean;
  allowEmptyValue?: boolean;
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
  schema?: ReferenceObject | SchemaObject;
  example?: any;
  examples?: { [media: string]: ReferenceObject | ExampleObject };
  content?: { [media: string]: MediaTypeObject };
}

/**
 * Schema object union type
 */
type SchemaObject = ArraySchemaObject | NonArraySchemaObject;

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

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

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

/**
 * Discriminator object for polymorphism
 */
interface DiscriminatorObject {
  propertyName: string;
  mapping?: { [value: string]: string };
}

/**
 * XML metadata object
 */
interface XMLObject {
  name?: string;
  namespace?: string;
  prefix?: string;
  attribute?: boolean;
  wrapped?: boolean;
}

/**
 * JSON Reference object
 */
interface ReferenceObject {
  $ref: string;
}

/**
 * Example object
 */
interface ExampleObject {
  summary?: string;
  description?: string;
  value?: any;
  externalValue?: string;
}

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

/**
 * Collection of response objects
 */
interface ResponsesObject {
  [code: string]: ReferenceObject | ResponseObject;
}

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

/**
 * Media type object
 */
interface MediaTypeObject {
  schema?: ReferenceObject | SchemaObject;
  example?: any;
  examples?: { [media: string]: ReferenceObject | ExampleObject };
  encoding?: { [media: string]: EncodingObject };
}

/**
 * Encoding object for multipart/form-data
 */
interface EncodingObject {
  contentType?: string;
  headers?: { [header: string]: ReferenceObject | HeaderObject };
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
}

/**
 * Link object for response linking
 */
interface LinkObject {
  operationRef?: string;
  operationId?: string;
  parameters?: { [parameter: string]: any };
  requestBody?: any;
  description?: string;
  server?: ServerObject;
}

/**
 * Callback object for webhooks
 */
interface CallbackObject {
  [url: string]: PathItemObject;
}

/**
 * Security requirement object
 */
interface SecurityRequirementObject {
  [name: string]: string[];
}

/**
 * Security scheme object union type
 */
type SecuritySchemeObject =
  | HttpSecurityScheme
  | ApiKeySecurityScheme
  | OAuth2SecurityScheme
  | OpenIdSecurityScheme;

/**
 * HTTP security scheme
 */
interface HttpSecurityScheme {
  type: 'http';
  description?: string;
  scheme: string;
  bearerFormat?: string;
}

/**
 * API key security scheme
 */
interface ApiKeySecurityScheme {
  type: 'apiKey';
  description?: string;
  name: string;
  in: string;
}

/**
 * OAuth2 security scheme
 */
interface OAuth2SecurityScheme {
  type: 'oauth2';
  description?: string;
  flows: {
    implicit?: {
      authorizationUrl: string;
      refreshUrl?: string;
      scopes: { [scope: string]: string };
    };
    password?: {
      tokenUrl: string;
      refreshUrl?: string;
      scopes: { [scope: string]: string };
    };
    clientCredentials?: {
      tokenUrl: string;
      refreshUrl?: string;
      scopes: { [scope: string]: string };
    };
    authorizationCode?: {
      authorizationUrl: string;
      tokenUrl: string;
      refreshUrl?: string;
      scopes: { [scope: string]: string };
    };
  };
}

/**
 * OpenID Connect security scheme
 */
interface OpenIdSecurityScheme {
  type: 'openIdConnect';
  description?: string;
  openIdConnectUrl: string;
}

/**
 * Reusable components object
 */
interface ComponentsObject {
  schemas?: { [key: string]: ReferenceObject | SchemaObject };
  responses?: { [key: string]: ReferenceObject | ResponseObject };
  parameters?: { [key: string]: ReferenceObject | ParameterObject };
  examples?: { [key: string]: ReferenceObject | ExampleObject };
  requestBodies?: { [key: string]: ReferenceObject | RequestBodyObject };
  headers?: { [key: string]: ReferenceObject | HeaderObject };
  securitySchemes?: { [key: string]: ReferenceObject | SecuritySchemeObject };
  links?: { [key: string]: ReferenceObject | LinkObject };
  callbacks?: { [key: string]: ReferenceObject | CallbackObject };
}

import { OpenAPIV3 } from "openapi-types";

// OpenAPI 3.0 document
const apiDoc: OpenAPIV3.Document = {
  openapi: "3.0.3",
  info: {
    title: "Pet Store API",
    version: "1.0.0",
    description: "A sample API for pet store operations"
  },
  servers: [
    {
      url: "https://api.petstore.com/v1",
      description: "Production server"
    }
  ],
  paths: {
    "/pets": {
      get: {
        summary: "List all pets",
        operationId: "listPets",
        responses: {
          "200": {
            description: "A list of pets",
            content: {
              "application/json": {
                schema: {
                  type: "array",
                  items: {
                    $ref: "#/components/schemas/Pet"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      Pet: {
        type: "object",
        required: ["id", "name"],
        properties: {
          id: {
            type: "integer",
            format: "int64"
          },
          name: {
            type: "string"
          },
          tag: {
            type: "string"
          }
        }
      }
    }
  }
};

// Using HTTP methods enum
function supportsMethod(method: string): method is OpenAPIV3.HttpMethods {
  return Object.values(OpenAPIV3.HttpMethods).includes(method as OpenAPIV3.HttpMethods);
}

// Schema validation
function isArraySchema(schema: OpenAPIV3.SchemaObject): schema is OpenAPIV3.ArraySchemaObject {
  return 'type' in schema && schema.type === 'array';
}