oas
Version:
Comprehensive tooling for working with OpenAPI definitions
284 lines (281 loc) • 12.2 kB
text/typescript
import { O as Operation, W as Webhook, E as Extensions } from './extensions-DCqurkah.cjs';
import { OASDocument, User, ServerVariable, ServerVariablesObject, Servers, HttpMethods, PathsObject, AuthForHAR } from './types.cjs';
import { Match, ParamData } from 'path-to-regexp';
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 {
/**
* An OpenAPI API 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;
};
/**
* @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: Record<string, unknown> | OASDocument, 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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.
*
* @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;
/**
* 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[];
/**
* Dereference the current OAS definition 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;
/**
* Preserve component schema names within themselves as a `title`.
*/
preserveRefAsJSONSchemaTitle?: boolean;
}): Promise<(typeof this.promises)[] | boolean>;
}
export = Oas;