oas/dist/index.d.cts

Comprehensive tooling for working with OpenAPI definitions

import { PathsObject, HttpMethods, OASDocument, User, ServerVariable, ServerVariablesObject, Servers, AuthForHAR, SecuritySchemeObject, DataForHAR, SchemaObject, OAS31Document, OperationObject, SecurityRequirementObject, KeyedSecuritySchemeObject, SecurityType, TagObject, ParameterObject, SchemaWrapper, MediaTypeObject, ResponseObject, PathItemObject } from './types.cjs';
import { Match, ParamData } from 'path-to-regexp';
import { g as getParametersAsJSONSchemaOptions } from './get-parameters-as-json-schema-Cbp85O99.cjs';
import 'json-schema';
import 'openapi-types';

interface PathMatch {
    match?: Match<ParamData>;
    operation: PathsObject;
    url: {
        method?: HttpMethods;
        nonNormalizedPath: string;
        origin: string;
        path: string;
        slugs: Record<string, string>;
    };
}
type PathMatches = PathMatch[];

declare class Oas {
    /**
     * The current OpenAPI definition.
     */
    api: OASDocument;
    /**
     * The current user that we should use when pulling auth tokens from security schemes.
     */
    user: User;
    /**
     * Internal storage array that the library utilizes to keep track of the times the
     * {@see Oas.dereference} has been called so that if you initiate multiple promises they'll all
     * end up returning the same data set once the initial dereference call completed.
     */
    protected promises: {
        reject: any;
        resolve: any;
    }[];
    /**
     * Internal storage array that the library utilizes to keep track of its `dereferencing` state so
     * it doesn't initiate multiple dereferencing processes.
     */
    protected dereferencing: {
        circularRefs: string[];
        complete: boolean;
        processing: boolean;
    };
    /**
     * Have the component schemas within this API definition been decorated with our
     * `x-readme-ref-name` extension?
     *
     * @see {@link decorateComponentSchemas}
     */
    protected schemasDecorated: boolean;
    /**
     * @param oas An OpenAPI definition.
     * @param user The information about a user that we should use when pulling auth tokens from
     *    security schemes.
     */
    constructor(oas: OASDocument | string, user?: User);
    /**
     * This will initialize a new instance of the `Oas` class. This method is useful if you're using
     * Typescript and are attempting to supply an untyped JSON object into `Oas` as it will force-type
     * that object to an `OASDocument` for you.
     *
     * @param oas An OpenAPI definition.
     * @param user The information about a user that we should use when pulling auth tokens from
     *    security schemes.
     */
    static init(oas: OASDocument | Record<string, unknown>, user?: User): Oas;
    /**
     * Retrieve the OpenAPI version that this API definition is targeted for.
     */
    getVersion(): string;
    /**
     * Retrieve the current OpenAPI API Definition.
     *
     */
    getDefinition(): OASDocument;
    url(selected?: number, variables?: ServerVariable): string;
    variables(selected?: number): ServerVariablesObject;
    defaultVariables(selected?: number): ServerVariable;
    splitUrl(selected?: number): ({
        /**
         * A unique key, where the `value` is concatenated to its index
         */
        key: string;
        type: 'text';
        value: string;
    } | {
        /**
         * An optional description for the server variable.
         *
         * @see {@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-4}
         */
        description?: string;
        /**
         * An enumeration of string values to be used if the substitution options are from a limited set.
         *
         * @see {@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-4}
         */
        enum?: string[];
        /**
         * A unique key, where the `value` is concatenated to its index
         */
        key: string;
        type: 'variable';
        value: string;
    })[];
    /**
     * With a fully composed server URL, run through our list of known OAS servers and return back
     * which server URL was selected along with any contained server variables split out.
     *
     * For example, if you have an OAS server URL of `https://{name}.example.com:{port}/{basePath}`,
     * and pass in `https://buster.example.com:3000/pet` to this function, you'll get back the
     * following:
     *
     *    { selected: 0, variables: { name: 'buster', port: 3000, basePath: 'pet' } }
     *
     * Re-supplying this data to `oas.url()` should return the same URL you passed into this method.
     *
     * @param baseUrl A given URL to extract server variables out of.
     */
    splitVariables(baseUrl: string): Servers | false;
    /**
     * Replace templated variables with supplied data in a given URL.
     *
     * There are a couple ways that this will utilize variable data:
     *
     *  - Supplying a `variables` object. If this is supplied, this data will always take priority.
     *    This incoming `variables` object can be two formats:
     *    `{ variableName: { default: 'value' } }` and `{ variableName: 'value' }`. If the former is
     *    present, that will take precedence over the latter.
     *  - If the supplied `variables` object is empty or does not match the current template name,
     *    we fallback to the data stored in `this.user` and attempt to match against that.
     *    See `getUserVariable` for some more information on how this data is pulled from `this.user`.
     *
     * If no variables supplied match up with the template name, the template name will instead be
     * used as the variable data.
     *
     * @param url A URL to swap variables into.
     * @param variables An object containing variables to swap into the URL.
     */
    replaceUrl(url: string, variables?: ServerVariable): string;
    /**
     * Retrieve an Operation of Webhook class instance for a given path and method.
     *
     * @param path Path to lookup and retrieve.
     * @param method HTTP Method to retrieve on the path.
     */
    operation(path: string, method: HttpMethods, opts?: {
        /**
         * If you prefer to first look for a webhook with this path and method.
         */
        isWebhook?: boolean;
    }): Operation;
    findOperationMatches(url: string): PathMatches | undefined;
    /**
     * Discover an operation in an OAS from a fully-formed URL and HTTP method. Will return an object
     * containing a `url` object and another one for `operation`. This differs from `getOperation()`
     * in that it does not return an instance of the `Operation` class.
     *
     * @param url A full URL to look up.
     * @param method The cooresponding HTTP method to look up.
     */
    findOperation(url: string, method: HttpMethods): PathMatch | undefined;
    /**
     * Discover an operation in an OAS from a fully-formed URL without an HTTP method. Will return an
     * object containing a `url` object and another one for `operation`.
     *
     * @param url A full URL to look up.
     */
    findOperationWithoutMethod(url: string): PathMatch | undefined;
    /**
     * Retrieve an operation in an OAS from a fully-formed URL and HTTP method. Differs from
     * `findOperation` in that while this method will return an `Operation` instance,
     * `findOperation()` does not.
     *
     * @param url A full URL to look up.
     * @param method The cooresponding HTTP method to look up.
     */
    getOperation(url: string, method: HttpMethods): Operation | undefined;
    /**
     * Retrieve an operation in an OAS by an `operationId`.
     *
     * If an operation does not have an `operationId` one will be generated in place, using the
     * default behavior of `Operation.getOperationId()`, and then asserted against your query.
     *
     * Note that because `operationId`s are unique that uniqueness does include casing so the ID
     * you are looking for will be asserted as an exact match.
     *
     * @see {Operation.getOperationId()}
     * @param id The `operationId` to look up.
     */
    getOperationById(id: string): Operation | Webhook | undefined;
    /**
     * With an object of user information, retrieve the appropriate API auth keys from the current
     * OAS definition.
     *
     * @see {@link https://docs.readme.com/docs/passing-data-to-jwt}
     * @param user User
     * @param selectedApp The user app to retrieve an auth key for.
     */
    getAuth(user: User, selectedApp?: number | string): AuthForHAR;
    /**
     * Determine if a security scheme exists within the API definition.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#security-scheme-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object}
     * @param name The name of the security scheme to check for.
     */
    hasSecurityScheme(name: string): boolean;
    /**
     * Retrieve a security scheme from the API definition.
     *
     * If the found security scheme is a `$ref` pointer it will be lazily dereferenced; if the scheme
     * cannot be resolved after that process (eg. it's circular or is an invalid `$ref`) then
     * `undefined` will be returned.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#security-scheme-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object}
     * @param name The name of the security scheme to retrieve.
     */
    getSecurityScheme(name: string): SecuritySchemeObject | undefined;
    /**
     * Returns the `paths` object that exists in this API definition but with every `method` mapped
     * to an instance of the `Operation` class.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
     */
    getPaths(): Record<string, Record<HttpMethods, Operation | Webhook>>;
    /**
     * Returns the `webhooks` object that exists in this API definition but with every `method`
     * mapped to an instance of the `Webhook` class.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
     */
    getWebhooks(): Record<string, Record<HttpMethods, Webhook>>;
    /**
     * Return an array of all tag names that exist on this API definition.
     *
     * If the API definition uses the `x-disable-tag-sorting` extension then tags will be returned in
     * the order they're defined.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#openapi-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
     * @param setIfMissing If a tag is not present on an operation that operations path will be added
     *    into the list of tags returned.
     */
    getTags(setIfMissing?: boolean): string[];
    /**
     * Determine if a given a custom specification extension exists within the API definition.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     * @param extension Specification extension to lookup.
     */
    hasExtension(extension: string): boolean;
    /**
     * Retrieve a custom specification extension off of the API definition.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     * @param extension Specification extension to lookup.
     */
    getExtension(extension: string | keyof Extensions, operation?: Operation): any;
    /**
     * Determine if a given OpenAPI custom extension is valid or not.
     *
     * @see {@link https://docs.readme.com/docs/openapi-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     * @param extension Specification extension to validate.
     * @throws
     */
    validateExtension(extension: keyof Extensions): void;
    /**
     * Validate all of our custom or known OpenAPI extensions, throwing exceptions when necessary.
     *
     * @see {@link https://docs.readme.com/docs/openapi-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     */
    validateExtensions(): void;
    /**
     * Dereference the current API definition so it can be parsed free from the hassle of resolving
     * `$ref` schemas and circular structures.
     *
     */
    dereference(opts?: {
        /**
         * A callback method can be supplied to be called when dereferencing is complete. Used for
         * debugging that the multi-promise handling within this method works.
         *
         * @private
         */
        cb?: () => void;
    }): Promise<(typeof this.promises)[] | boolean>;
    /**
     * Determine if the current API definition has been dereferenced or not.
     *
     * @see Oas.dereference
     */
    isDereferenced(): boolean;
    /**
     * Retrieve any circular `$ref` pointers that maybe present within the API definition.
     *
     * This method requires that you first dereference the definition.
     *
     * @see Oas.dereference
     */
    getCircularReferences(): string[];
}

interface MediaTypeExample {
    description?: string;
    summary?: string;
    title?: string;
    value: unknown;
}

interface ResponseExample {
    mediaTypes: Record<string, MediaTypeExample[]>;
    onlyHeaders?: boolean;
    status: string;
}

interface CallbackExample {
    example: ResponseExample[];
    expression: string;
    identifier: string;
    method: string;
}

type ExampleGroups = Record<string, {
    /**
     * Array of custom code samples that contain `correspondingExample` key.
     * Mutually exclusive of `request`. Note that if this object is present,
     * there may or may not be corresponding responses in the `response` object.
     */
    customCodeSamples?: (NonNullable<Extensions['code-samples']>[number] & {
        /**
         * The index in the originally defined `code-samples` array
         */
        originalIndex: number;
    })[];
    /**
     * Title of example group. This is derived from the `summary` field of one of
     * the operation's example objects. The precedence is as follows (from highest to lowest):
     * 1. The first custom code sample's `name` field.
     * 2. The first request parameter (e.g., cookie/header/path/query) example object that
     *  contains a `summary` field
     * 3. The request body example object's `summary` field
     * 4. The response example object's `summary` field
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#example-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#example-object}
     */
    name: string;
    /**
     * Object containing the example request data for the current example key.
     * Mutually exclusive of `customCodeSamples`. If `customCodeSamples` is present,
     * any request example definitions are ignored.
     */
    request?: DataForHAR;
    /**
     * Object containing the example response data for the current example key.
     */
    response?: {
        /**
         * The content type of the current example
         *
         * @example "application/json"
         * @example "text/plain"
         */
        mediaType: string;
        /**
         * The entire response example object. The example value itself is contained
         * within `value`.
         *
         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#example-object}
         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#example-object}
         */
        mediaTypeExample: MediaTypeExample;
        /**
         * The HTTP status code for the current response example
         *
         * @example "2xx"
         * @example "400"
         */
        status: string;
    };
}>;

interface RequestBodyExample {
    examples: MediaTypeExample[];
    mediaType: string;
}

interface OperationIDGeneratorOptions {
    /**
     * Generate a JS method-friendly operation ID when one isn't present.
     *
     * For backwards compatiblity reasons this option will be indefinitely supported however we
     * recommend using `friendlyCase` instead as it's a heavily improved version of this option.
     *
     * @see {friendlyCase}
     * @deprecated
     */
    camelCase?: boolean;
    /**
     * Generate a human-friendly, but still camelCase, operation ID when one isn't present. The
     * difference between this and `camelCase` is that this also ensure that consecutive words are
     * not present in the resulting ID. For example, for the endpoint `/candidate/{candidate}` will
     * return `getCandidateCandidate` for `camelCase` however `friendlyCase` will return
     * `getCandidate`.
     *
     * The reason this friendliness is just not a part of the `camelCase` option is because we have
     * a number of consumers of the old operation ID style and making that change there would a
     * breaking change that we don't have any easy way to resolve.
     */
    friendlyCase?: boolean;
}

interface ResponseSchemaObject {
    description?: string;
    label: string;
    schema: SchemaObject;
    type: string[] | string;
}

declare class Operation {
    /**
     * The `Oas` instance that this operation belongs to.
     */
    oas: Oas;
    /**
     * Schema of the operation from the API Definition.
     */
    schema: OperationObject;
    /**
     * OpenAPI API Definition that this operation originated from.
     */
    api: OASDocument;
    /**
     * Path that this operation is targeted towards.
     */
    path: string;
    /**
     * HTTP Method that this operation is targeted towards.
     */
    method: HttpMethods;
    /**
     * The primary Content Type that this operation accepts.
     */
    contentType: string | undefined;
    /**
     * An object with groups of all example definitions (body/header/query/path/response/etc.)
     */
    exampleGroups: ExampleGroups | undefined;
    /**
     * Request body examples for this operation.
     */
    requestBodyExamples: RequestBodyExample[] | undefined;
    /**
     * Response examples for this operation.
     */
    responseExamples: ResponseExample[] | undefined;
    /**
     * Callback examples for this operation (if it has callbacks).
     */
    callbackExamples: CallbackExample[] | undefined;
    /**
     * Flattened out arrays of both request and response headers that are utilized on this operation.
     */
    headers: {
        request: string[];
        response: string[];
    };
    /**
     * Internal storage array that the library utilizes to keep track of the times the
     * {@see Operation.dereference} has been called so that if you initiate multiple promises they'll
     * all end up returning the same data set once the initial dereference call completed.
     */
    protected promises: {
        reject: any;
        resolve: any;
    }[];
    /**
     * Internal storage array that the library utilizes to keep track of its `dereferencing` state so
     * it doesn't initiate multiple dereferencing processes.
     */
    protected dereferencing: {
        circularRefs: string[];
        complete: boolean;
        processing: boolean;
    };
    /**
     * Have the component schemas within this API definition been decorated with our
     * `x-readme-ref-name` extension?
     *
     * @see {@link decorateComponentSchemas}
     */
    protected schemasDecorated: boolean;
    constructor(oas: Oas, path: string, method: HttpMethods, operation: OperationObject);
    /**
     * Retrieve the `summary` for this operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
     */
    getSummary(): string | undefined;
    /**
     * Retrieve the `description` for this operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
     */
    getDescription(): string | undefined;
    /**
     * Retrieve the primary content type for this operation. If multiple exist, the first JSON-like
     * type will be returned.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
     */
    getContentType(): string;
    /**
     * Checks if the current operation has a `x-www-form-urlencoded` content type payload.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
     */
    isFormUrlEncoded(): boolean;
    /**
     * Checks if the current operation has a mutipart content type payload.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
     */
    isMultipart(): boolean;
    /**
     * Checks if the current operation has a JSON-like content type payload.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
     */
    isJson(): boolean;
    /**
     * Checks if the current operation has an XML content type payload.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
     */
    isXml(): boolean;
    /**
     * Checks if the current operation is a webhook or not.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#oas-webhooks}
     */
    isWebhook(): boolean;
    /**
     * Returns an array of all security requirements associated wtih this operation. If none are
     * defined at the operation level, the securities for the entire API definition are returned
     * (with an empty array as a final fallback).
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#security-requirement-object}
     */
    getSecurity(): SecurityRequirementObject[];
    /**
     * Retrieve a collection of grouped security schemes. The inner array determines AND-grouped
     * security schemes, the outer array determines OR-groups.
     *
     * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-requirement-object}
     * @param filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent
     *    security schemes, rather than returning `false`.
     */
    getSecurityWithTypes(filterInvalid?: boolean): ((false | {
        security: KeyedSecuritySchemeObject;
        type: SecurityType;
    })[] | false)[];
    /**
     * Retrieve an object where the keys are unique scheme types, and the values are arrays
     * containing each security scheme of that type.
     *
     */
    prepareSecurity(): Record<SecurityType, KeyedSecuritySchemeObject[]>;
    /**
     * Retrieve all of the headers, request and response, that are associated with this operation.
     *
     */
    getHeaders(): Operation['headers'];
    /**
     * Determine if this operation has an `operationId` present in its schema. Note that if one is
     * present in the schema but is an empty string then this will return `false`.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
     */
    hasOperationId(): boolean;
    /**
     * Determine if an operation has an `operationId` present in its schema. Note that if one is
     * present in the schema but is an empty string then this will return `false`.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
     */
    static hasOperationId(schema: OperationObject): boolean;
    /**
     * Get an `operationId` for this operation. If one is not present (it's not required by the spec!)
     * a hash of the path and method will be returned instead.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
     */
    getOperationId(opts?: OperationIDGeneratorOptions): string;
    /**
     * Get an `operationId` for an operation. If one is not present (it's not required by the spec!)
     * a hash of the path and method will be returned instead.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
     */
    static getOperationId(path: string, method: string, schema: OperationObject, opts?: OperationIDGeneratorOptions): string;
    /**
     * Return an array of all tags, and their metadata, that exist on this operation.
     *
     */
    getTags(): TagObject[];
    /**
     * Return is the operation is flagged as `deprecated` or not.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdeprecated}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-deprecated}
     */
    isDeprecated(): boolean;
    /**
     * Determine if the operation has any (non-request body) parameters.
     *
     */
    hasParameters(): boolean;
    /**
     * Return the parameters (non-request body) on the operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
     */
    getParameters(): ParameterObject[];
    /**
     * Determine if this operation has any required parameters.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
     */
    hasRequiredParameters(): boolean;
    /**
     * Convert the operation into an array of JSON Schema schemas for each available type of
     * parameter available on the operation.
     *
     * Note that this method is not compatible with an operation or OpenAPI definition that has been
     * processed with `.dereference()`. This method can only be called with the _original_ API
     * definition that was used to initialize the `Operation` and `Oas` instance. If a dereferenced
     * schema is present when this is called a `TypeError` will be thrown.
     *
     * @throws {TypeError} If the operation or OpenAPI definition has been run through `.dereference().`
     *
     */
    getParametersAsJSONSchema(opts?: getParametersAsJSONSchemaOptions): SchemaWrapper[] | null;
    /**
     * Get a single response for this status code, formatted as JSON schema.
     *
     * Note that this method is not compatible with an operation or OpenAPI definition that has been
     * processed with `.dereference()`. This method can only be called with the _original_ API
     * definition that was used to initialize the `Operation` and `Oas` instance. If a dereferenced
     * schema is present when this is called a `TypeError` will be thrown.
     *
     * @param statusCode Status code to pull a JSON Schema response for.
     * @param opts Options for schema generation.
     * @param opts.contentType Optional content-type to use. If specified and the response doesn't have
     *   this content-type, the function will return null.
     */
    getResponseAsJSONSchema(statusCode: number | string, opts?: {
        /**
         * If you wish to include discriminator mapping `$ref` components alongside your
         * `discriminator` in schemas. Defaults to `true`.
         */
        includeDiscriminatorMappingRefs?: boolean;
        /**
         * Optional content-type to use. If specified and the response doesn't have this content-type,
         * the function will return null.
         */
        contentType?: string;
    }): ResponseSchemaObject[] | null;
    /**
     * Get an array of all valid response status codes for this operation.
     *
     */
    getResponseStatusCodes(): string[];
    /**
     * Retrieve an array of all content types that this operation can return.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object}
     */
    getResponseContentTypes(): string[];
    /**
     * Determine if the operation has any request bodies.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationrequestbody}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-request-body}
     */
    hasRequestBody(): boolean;
    /**
     * Return the current `requestBody` object, dereferencing it in the process if it's a `$ref`
     * pointer.
     *
     */
    private getResolvedRequestBody;
    /**
     * Retrieve the list of all available media types that the operations request body can accept.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
     */
    getRequestBodyMediaTypes(): string[];
    /**
     * Determine if this operation has a required request body.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
     */
    hasRequiredRequestBody(): boolean;
    /**
     * Retrieve a specific request body content schema off this operation.
     *
     * If no media type is supplied this will return either the first available JSON-like request
     * body, or the first available if there are no JSON-like media types present. The return value
     * is an object containing the selected media type, the media type object, and an optional
     * description.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
     * @param mediaType Specific request body media type to retrieve if present.
     */
    getRequestBody(mediaType?: string): false | {
        mediaType: string;
        mediaTypeObject: MediaTypeObject;
        description?: string;
    };
    /**
     * Retrieve an array of request body examples that this operation has.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#request-body-examples}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#request-body-examples}
     */
    getRequestBodyExamples(): RequestBodyExample[];
    /**
     * Return a specific response out of the operation by a given HTTP status code.
     *
     * @param statusCode Status code to pull a response object for.
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object}
     */
    getResponseByStatusCode(statusCode: number | string): ResponseObject | false;
    /**
     * Retrieve an array of response examples that this operation has.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object-examples}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object-examples}
     */
    getResponseExamples(): ResponseExample[];
    /**
     * Determine if the operation has callbacks.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
     */
    hasCallbacks(): boolean;
    /**
     * Retrieve a specific callback.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
     * @param identifier Callback identifier to look for.
     * @param expression Callback expression to look for.
     * @param method HTTP Method on the callback to look for.
     */
    getCallback(identifier: string, expression: string, method: HttpMethods): Callback | false;
    /**
     * Retrieve an array of operations created from each callback.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
     */
    getCallbacks(): Callback[];
    /**
     * Retrieve an array of callback examples that this operation has.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
     */
    getCallbackExamples(): CallbackExample[];
    /**
     * Determine if a given a custom specification extension exists within the operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     * @param extension Specification extension to lookup.
     */
    hasExtension(extension: string): boolean;
    /**
     * Retrieve a custom specification extension off of the operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions}
     * @param extension Specification extension to lookup.
     *
     * @deprecated Use `oas.getExtension(extension, operation)` instead.
     */
    getExtension(extension: string | keyof Extensions): any;
    /**
     * Returns an object with groups of all example definitions (body/header/query/path/response/etc.).
     * The examples are grouped by their key when defined via the `examples` map.
     *
     * Any custom code samples defined via the `x-readme.code-samples` extension are returned,
     * regardless of if they have a matching response example.
     *
     * For standard OAS request parameter (e.g., body/header/query/path/etc.) examples,
     * they are only present in the return object if they have a corresponding response example
     * (i.e., a response example with the same key in the `examples` map).
     */
    getExampleGroups(): ExampleGroups;
    /**
     * Dereference the current operation schema so it can be parsed free of worries of `$ref` schemas
     * and circular structures.
     *
     */
    dereference(opts?: {
        /**
         * A callback method can be supplied to be called when dereferencing is complete. Used for
         * debugging that the multi-promise handling within this method works.
         *
         * @private
         */
        cb?: () => void;
    }): Promise<(typeof this.promises)[] | boolean>;
    /**
     * Determine if the current operation schema, or the OpenAPI definition it's part of, has been
     * dereferenced or not with `.dereference()`.
     *
     * @see Operation.dereference
     */
    isDereferenced(): boolean;
    /**
     * Retrieve any circular `$ref` pointers that maybe present within operation schema.
     *
     * This method requires that you first dereference the definition.
     *
     * @see Operation.dereference
     */
    getCircularReferences(): string[];
}
declare class Callback extends Operation {
    /**
     * The identifier that this callback is set to.
     */
    identifier: string;
    /**
     * The parent path item object that this Callback exists within.
     */
    parentSchema: PathItemObject;
    constructor(oas: Oas, path: string, method: HttpMethods, operation: OperationObject, identifier: string, parentPathItem: PathItemObject);
    /**
     * Return the primary identifier for this callback.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
     */
    getIdentifier(): string;
    /**
     * Retrieve the `summary` for this callback.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
     */
    getSummary(): string | undefined;
    /**
     * Retrieve the `description` for this operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
     */
    getDescription(): string | undefined;
    /**
     * Return the parameters (non-request body) on the operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
     */
    getParameters(): ParameterObject[];
}
declare class Webhook extends Operation {
    /**
     * OpenAPI API Definition that this webhook originated from.
     */
    api: OAS31Document;
    /**
     * Retrieve the `summary` for this callback.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
     */
    getSummary(): string | undefined;
    /**
     * Retrieve the `description` for this operation.
     *
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
     */
    getDescription(): string | undefined;
}

/**
 * Enables custom-written code samples to be set for your operations. Use this if you have specific
 * formatting that may not be followed by the auto-generated code samples. Custom code samples are
 * treated as static content.
 *
 * This extension only be placed at the operation level.
 *
 * @defaultValue []
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#custom-code-samples}
 * @example
 * {
 *  "x-readme": {
 *    "code-samples": [
 *      {
 *        "language": "curl",
 *        "code": "curl -X POST https://api.example.com/v2/alert",
 *        "name": "Custom cURL snippet",
 *        "install": "brew install curl"
 *      },
 *      {
 *        "language": "php",
 *        "code": "<?php echo \"This is our custom PHP code snippet.\"; ?>",
 *        "name": "Custom PHP snippet"
 *      }
 *    ]
 *  }
 * }
 */
declare const CODE_SAMPLES = "code-samples";
/**
 * Disables the API Explorer's "Try It" button, preventing users from making API requests from
 * within your docs. Users will still be able to fill out any entry fields (path or query
 * parameters, etc.), and code snippets will be auto-generated based on the user's input, however
 * to interact with your API the user will need to copy the code snippet and execute it outside of
 * your docs.
 *
 * This **does not** disable your API Reference documentation.
 *
 * @defaultValue true
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-the-api-explorer}
 * @example
 * {
 *  "x-readme": {
 *    "explorer-enabled": true
 *  }
 * }
 */
declare const EXPLORER_ENABLED = "explorer-enabled";
/**
 * Adds static headers to add to each request. Use this when there are specific headers unique to
 * your API.
 *
 * @defaultValue []
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#static-headers}
 * @example
 * {
 *  "x-readme": {
 *    "headers": [
 *      {
 *        "key": "X-Static-Header-One",
 *        "value": "owlbert"
 *      },
 *      {
 *        "key": "X-Static-Header-Two",
 *        "value": "owlivia"
 *      }
 *    ]
 *  }
 * }
 */
declare const HEADERS = "headers";
/**
 * Allows you to mark an API endpoint, or _every_ API endpoint if defined in the root, as being
 * internal and hidden from your public API reference.
 *
 * @defaultValue false
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#internal}
 * @example
 * {
 *  "x-internal": true
 * }
 * @example
 * {
 *  "x-readme": {
 *    "internal": true
 *  }
 * }
 */
declare const INTERNAL = "internal";
/**
 * Disables API requests from the API Explorer's "Try It" button from being sent into our [API
 * Metrics](https://readme.com/metrics) for you and your users. Additionally on any API endpoint
 * that this is disabled on your users will not see lists or graphs of previous requests they've
 * made against that API endpoint — either through the API Explorer's interactivity or through one
 * of our [Metrics SDKs](https://docs.readme.com/main/docs/api-metrics-setup) (if you have those
 * installed on your API).
 *
 * @defaultValue true
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-api-metrics}
 * @example
 * {
 *  "x-readme": {
 *    "metrics-defaults": false
 *  }
 * }
 */
declare const METRICS_ENABLED = "metrics-enabled";
/**
 * Configuration options for OAuth flows in the API Explorer.
 *
 * @defaultValue {}
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#oauth-configuration-options}
 * @example
 * {
 *  "x-readme": {
 *    "oauth-options": {
 *      "scopeSeparator": ",",
 *      "useInsecureClientAuthentication": true,
 *      "usePkce": false
 *    }
 *  }
 * }
 */
declare const OAUTH_OPTIONS = "oauth-options";
/**
 * Controls the order of parameters on your API Reference pages.
 *
 * Your custom ordering **must** contain all of our available parameter types:
 *
 *  - `path`: Path parameters
 *  - `query`: Query parameters
 *  - `body`: Non-`application/x-www-form-urlencoded` request body payloads
 *  - `cookie`: Cookie parameters
 *  - `form`: `application/x-www-form-urlencoded` request body payloads
 *  - `header`: Header parameters
 *
 * @defaultValue ['path', 'query', 'body', 'cookie', 'form', 'header']
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#parameter-ordering}
 * @example
 * {
 *  "x-readme": {
 *    "parameter-ordering": ['path', 'query', 'header', 'cookie', 'body', 'form']
 *  }
 * }
 */
declare const PARAMETER_ORDERING = "parameter-ordering";
/**
 * Toggles the CORS proxy used when making API requests from within your docs (via the "Try It"
 * button). If your API is already set up to return CORS headers, you can safely disable this
 * feature.
 *
 * Disabling the CORS proxy will make the request directly from the user's browser and will prevent
 * [Metrics](https://docs.readme.com/main/docs/getting-started-with-metrics) data from being logged
 * by us unless [Metrics have already set up on your backend](https://docs.readme.com/main/docs/api-metrics-setup).
 *
 * @defaultValue true
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#cors-proxy-enabled}
 * @example
 * {
 *  "x-readme": {
 *    "proxy-enabled": true
 *  }
 * }
 */
declare const PROXY_ENABLED = "proxy-enabled";
/**
 * Toggles what languages are shown by default for code samples in the API Explorer. This only
 * affects what languages are initially shown to the user; if the user picks another language from
 * the three-dot menu, that language and the respective auto-generated code snippet will also appear
 * as an option in the API Explorer.
 *
 * @defaultValue ['shell', 'node', 'ruby', 'php', 'python', 'java', 'csharp']
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#code-sample-languages}
 * @example
 * {
 *  "x-readme": {
 *    "samples-languages": ["shell", "node", "ruby", "javascript", "python"]
 *  }
 * }
 */
declare const SAMPLES_LANGUAGES = "samples-languages";
/**
 * Toggles if you will see code snippets for ReadMe's SDK code generator tool `api`.
 *
 * @defaultValue true
 * @see {@link https://api.readme.dev}
 * @example
 * {
 *  "x-readme": {
 *    "simple-mode": false
 *  }
 * }
 */
declare const SIMPLE_MODE = "simple-mode";
/**
 * If `true`, tags are generated from the file top-down. If `false`, we sort the tags
 * based off the `tags` array in the OAS file.
 *
 * @defaultValue false
 * @see {@link https://docs.readme.com/main/docs/openapi-extensions#disable-tag-sorting}
 * @example
 * {
 *  "x-readme": {
 *    "disable-tag-sorting": true
 *  }
 * }
 */
declare const DISABLE_TAG_SORTING = "disable-tag-sorting";
interface Extensions {
    [CODE_SAMPLES]: {
        /**
         * Custom code snippet
         * @example "curl -X POST https://api.example.com/v2/alert"
         */
        code: string;
        /**
         * Corresponding response example
         * @see {@link https://docs.readme.com/main/docs/openapi-extensions#corresponding-response-examples}
         */
        correspondingExample?: string;
        /**
         * Library installation instructions
         * @example "brew install httpie"
         * @example "npm install node-fetch@2 --save"
         */
        install?: string;
        /**
         * Language for syntax highlighting
         * @example shell
         */
        language: string;
        /**
         * Optional title for code sample
         * @example "Custom cURL snippet"
         */
        name?: string;
    }[] | undefined;
    [DISABLE_TAG_SORTING]: boolean;
    [EXPLORER_ENABLED]: boolean;
    [HEADERS]: Record<string, number | string>[] | undefined;
    [INTERNAL]: boolean;
    [METRICS_ENABLED]: boolean;
    [OAUTH_OPTIONS]: {
        /**
         * Scope separator for passing scopes. This value will be URL-encoded.
         *
         * @example ","
         * @example "+"
         * @default " "
         * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-3.3} Scope separators information from OAuth 2.0 specification
         */
        scopeSeparator?: string;
        /**
         * When enabled, the client credentials (i.e., `client_id` and `client_secret`) are sent in the request body (NOT recommended).
         * When disabled (the default), client credentials are sent using the HTTP Basic Authentication scheme.
         *
         * This is applicable for all requests to the token endpoint.
         *
         * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1}