OpenAPI 2.0 Types

/**
 * Root OpenAPI 2.0 (Swagger) document structure
 * @template T - Extension object type for custom properties
 */
interface Document<T extends {} = {}> {
  swagger: string;
  info: InfoObject;
  host?: string;
  basePath?: string;
  schemes?: string[];
  consumes?: MimeTypes;
  produces?: MimeTypes;
  paths: PathsObject<T>;
  definitions?: DefinitionsObject;
  parameters?: ParametersDefinitionsObject;
  responses?: ResponsesDefinitionsObject;
  securityDefinitions?: SecurityDefinitionsObject;
  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;
}

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

/**
 * External documentation object
 */
interface ExternalDocumentationObject {
  [index: string]: any;
  description?: string;
  url: string;
}

/**
 * Collection of API paths
 * @template T - Extension object type for custom properties
 */
interface PathsObject<T extends {} = {}> {
  [index: string]: PathItemObject<T>;
}

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

/**
 * Path item object with operation definitions
 * @template T - Extension object type for custom properties
 */
type PathItemObject<T extends {} = {}> = {
  $ref?: string;
  parameters?: Parameters;
} & {
  [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;
  consumes?: MimeTypes;
  produces?: MimeTypes;
  parameters?: Parameters;
  responses: ResponsesObject;
  schemes?: string[];
  deprecated?: boolean;
  security?: SecurityRequirementObject[];
} & T;

/**
 * MIME types array
 */
type MimeTypes = string[];

/**
 * Parameters array type
 */
type Parameters = (ReferenceObject | Parameter)[];

/**
 * Parameter union type
 */
type Parameter = InBodyParameterObject | GeneralParameterObject;

/**
 * Base parameter object
 */
interface ParameterObject {
  name: string;
  in: string;
  description?: string;
  required?: boolean;
  [index: string]: any;
}

/**
 * In-body parameter object
 */
interface InBodyParameterObject extends ParameterObject {
  schema: Schema;
}

/**
 * General parameter object
 */
interface GeneralParameterObject extends ParameterObject, ItemsObject {
  allowEmptyValue?: boolean;
}

/**
 * Parameter definitions collection
 */
interface ParametersDefinitionsObject {
  [index: string]: ParameterObject;
}

/**
 * Schema union type
 */
type Schema = SchemaObject | ReferenceObject;

/**
 * Schema definitions collection
 */
interface DefinitionsObject {
  [index: string]: SchemaObject;
}

/**
 * Schema object extending JSON Schema
 */
interface SchemaObject extends IJsonSchema {
  [index: string]: any;
  discriminator?: string;
  readOnly?: boolean;
  xml?: XMLObject;
  externalDocs?: ExternalDocumentationObject;
  example?: any;
  default?: any;
  items?: ItemsObject | ReferenceObject;
  properties?: {
    [name: string]: SchemaObject;
  };
}

/**
 * Items object for array definitions
 */
interface ItemsObject {
  type: string;
  format?: string;
  items?: ItemsObject | ReferenceObject;
  collectionFormat?: string;
  default?: any;
  maximum?: number;
  exclusiveMaximum?: boolean;
  minimum?: number;
  exclusiveMinimum?: boolean;
  maxLength?: number;
  minLength?: number;
  pattern?: string;
  maxItems?: number;
  minItems?: number;
  uniqueItems?: boolean;
  enum?: any[];
  multipleOf?: number;
  $ref?: string;
}

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

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

/**
 * Response union type
 */
type Response = ResponseObject | ReferenceObject;

/**
 * Collection of response objects
 */
interface ResponsesObject {
  [index: string]: Response | undefined;
  default?: Response;
}

/**
 * Response definitions collection
 */
interface ResponsesDefinitionsObject {
  [index: string]: ResponseObject;
}

/**
 * Response object definition
 */
interface ResponseObject {
  description: string;
  schema?: Schema;
  headers?: HeadersObject;
  examples?: ExampleObject;
}

/**
 * Headers collection object
 */
interface HeadersObject {
  [index: string]: HeaderObject;
}

/**
 * Header object definition
 */
interface HeaderObject extends ItemsObject {
  description?: string;
}

/**
 * Example object
 */
interface ExampleObject {
  [index: string]: any;
}

/**
 * Security definitions collection
 */
interface SecurityDefinitionsObject {
  [index: string]: SecuritySchemeObject;
}

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

/**
 * Security scheme object union type
 */
type SecuritySchemeObject =
  | SecuritySchemeBasic
  | SecuritySchemeApiKey
  | SecuritySchemeOauth2;

/**
 * Base security scheme object
 */
interface SecuritySchemeObjectBase {
  type: 'basic' | 'apiKey' | 'oauth2';
  description?: string;
}

/**
 * Basic authentication security scheme
 */
interface SecuritySchemeBasic extends SecuritySchemeObjectBase {
  type: 'basic';
}

/**
 * API key authentication security scheme
 */
interface SecuritySchemeApiKey extends SecuritySchemeObjectBase {
  type: 'apiKey';
  name: string;
  in: string;
}

/**
 * OAuth2 security scheme union type
 */
type SecuritySchemeOauth2 =
  | SecuritySchemeOauth2Implicit
  | SecuritySchemeOauth2AccessCode
  | SecuritySchemeOauth2Password
  | SecuritySchemeOauth2Application;

/**
 * OAuth2 scopes object
 */
interface ScopesObject {
  [index: string]: any;
}

/**
 * Base OAuth2 security scheme
 */
interface SecuritySchemeOauth2Base extends SecuritySchemeObjectBase {
  type: 'oauth2';
  flow: 'implicit' | 'password' | 'application' | 'accessCode';
  scopes: ScopesObject;
}

/**
 * OAuth2 implicit flow security scheme
 */
interface SecuritySchemeOauth2Implicit extends SecuritySchemeOauth2Base {
  flow: 'implicit';
  authorizationUrl: string;
}

/**
 * OAuth2 authorization code flow security scheme
 */
interface SecuritySchemeOauth2AccessCode extends SecuritySchemeOauth2Base {
  flow: 'accessCode';
  authorizationUrl: string;
  tokenUrl: string;
}

/**
 * OAuth2 password flow security scheme
 */
interface SecuritySchemeOauth2Password extends SecuritySchemeOauth2Base {
  flow: 'password';
  tokenUrl: string;
}

/**
 * OAuth2 client credentials flow security scheme
 */
interface SecuritySchemeOauth2Application extends SecuritySchemeOauth2Base {
  flow: 'application';
  tokenUrl: string;
}

import { OpenAPIV2 } from "openapi-types";

// Swagger 2.0 document
const swaggerDoc: OpenAPIV2.Document = {
  swagger: "2.0",
  info: {
    title: "Pet Store API",
    version: "1.0.0",
    description: "A sample API for pet store operations"
  },
  host: "api.petstore.com",
  basePath: "/v1",
  schemes: ["https"],
  consumes: ["application/json"],
  produces: ["application/json"],
  paths: {
    "/pets": {
      get: {
        summary: "List all pets",
        operationId: "listPets",
        produces: ["application/json"],
        responses: {
          "200": {
            description: "A list of pets",
            schema: {
              type: "array",
              items: {
                $ref: "#/definitions/Pet"
              }
            }
          }
        }
      },
      post: {
        summary: "Create a pet",
        operationId: "createPet",
        consumes: ["application/json"],
        parameters: [
          {
            name: "pet",
            in: "body",
            required: true,
            schema: {
              $ref: "#/definitions/Pet"
            }
          }
        ],
        responses: {
          "201": {
            description: "Pet created",
            schema: {
              $ref: "#/definitions/Pet"
            }
          }
        }
      }
    }
  },
  definitions: {
    Pet: {
      type: "object",
      required: ["name"],
      properties: {
        id: {
          type: "integer",
          format: "int64"
        },
        name: {
          type: "string"
        },
        tag: {
          type: "string"
        }
      }
    }
  },
  securityDefinitions: {
    api_key: {
      type: "apiKey",
      name: "api_key",
      in: "header"
    },
    petstore_auth: {
      type: "oauth2",
      flow: "implicit",
      authorizationUrl: "https://petstore.swagger.io/oauth/authorize",
      scopes: {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
};

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

// Parameter type checking
function isBodyParameter(param: OpenAPIV2.Parameter): param is OpenAPIV2.InBodyParameterObject {
  return 'schema' in param;
}

// Security scheme type checking
function isOAuth2Scheme(scheme: OpenAPIV2.SecuritySchemeObject): scheme is OpenAPIV2.SecuritySchemeOauth2 {
  return scheme.type === 'oauth2';
}