diff --git a/lib/index.d.ts b/lib/index.d.ts index 28549708..fc9c618b 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -1,11 +1,13 @@ import { OpenAPI } from "openapi-types"; +export = SwaggerParser; + /** * This is the default export of Swagger Parser. You can creates instances of this class using new SwaggerParser(), or you can just call its static methods. * * See https://apitools.dev/swagger-parser/docs/swagger-parser.html */ -export class SwaggerParser { +declare class SwaggerParser { /** * The `api` property is the parsed/bundled/dereferenced OpenAPI definition. This is the same value that is passed to the callback function (or Promise) when calling the parse, bundle, or dereference methods. @@ -203,7 +205,7 @@ export class SwaggerParser { } // eslint-disable-next-line no-redeclare -export namespace SwaggerParser { +declare namespace SwaggerParser { export type ApiCallback = (err: Error | null, api?: OpenAPI.Document) => any; export type $RefsCallback = (err: Error | null, $refs?: $Refs) => any; @@ -435,181 +437,3 @@ export namespace SwaggerParser { } } - -/** - * Parses, dereferences, and validates the given Swagger API. - * Depending on the options, validation can include JSON Schema validation and/or Swagger Spec validation. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#validateapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the dereferenced OpenAPI definition - */ -export function validate(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function validate(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function validate(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function validate(api: string | OpenAPI.Document): Promise; -export function validate(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function validate(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * Parses, dereferences, and validates the given Swagger API. - * Depending on the options, validation can include JSON Schema validation and/or Swagger Spec validation. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#validateapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the dereferenced OpenAPI definition - */ -export function validate(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function validate(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function validate(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function validate(api: string | OpenAPI.Document): Promise; -export function validate(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function validate(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * Dereferences all `$ref` pointers in the OpenAPI definition, replacing each reference with its resolved value. This results in an API definition that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references. - * - * The dereference method maintains object reference equality, meaning that all `$ref` pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of circular references, so be careful if you intend to serialize the API definition using `JSON.stringify()`. Consider using the bundle method instead, which does not create circular references. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#dereferenceapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the dereferenced OpenAPI definition - */ -export function dereference(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function dereference(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function dereference(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function dereference(api: string | OpenAPI.Document): Promise; -export function dereference(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function dereference(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * Dereferences all `$ref` pointers in the OpenAPI definition, replacing each reference with its resolved value. This results in an API definition that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references. - * - * The dereference method maintains object reference equality, meaning that all `$ref` pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of circular references, so be careful if you intend to serialize the API definition using `JSON.stringify()`. Consider using the bundle method instead, which does not create circular references. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#dereferenceapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the dereferenced OpenAPI definition - */ -export function dereference(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function dereference(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function dereference(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function dereference(api: string | OpenAPI.Document): Promise; -export function dereference(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function dereference(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * Bundles all referenced files/URLs into a single API definition that only has internal `$ref` pointers. This lets you split-up your API definition however you want while you're building it, but easily combine all those files together when it's time to package or distribute the API definition to other people. The resulting API definition size will be small, since it will still contain internal JSON references rather than being fully-dereferenced. - * - * This also eliminates the risk of circular references, so the API definition can be safely serialized using `JSON.stringify()`. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#bundleapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the bundled API definition object - */ -export function bundle(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function bundle(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function bundle(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function bundle(api: string | OpenAPI.Document): Promise; -export function bundle(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function bundle(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * Bundles all referenced files/URLs into a single API definition that only has internal `$ref` pointers. This lets you split-up your API definition however you want while you're building it, but easily combine all those files together when it's time to package or distribute the API definition to other people. The resulting API definition size will be small, since it will still contain internal JSON references rather than being fully-dereferenced. - * - * This also eliminates the risk of circular references, so the API definition can be safely serialized using `JSON.stringify()`. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#bundleapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive the bundled API definition object - */ -export function bundle(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function bundle(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function bundle(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function bundle(api: string | OpenAPI.Document): Promise; -export function bundle(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function bundle(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.* - * - * Parses the given OpenAPI definition file (in JSON or YAML format), and returns it as a JavaScript object. This method `does not` resolve `$ref` pointers or dereference anything. It simply parses one file and returns it. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#parseapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. The path can be absolute or relative. In Node, the path is relative to `process.cwd()`. In the browser, it's relative to the URL of the page. - * @param options (optional) - * @param callback (optional) A callback that will receive the parsed OpenAPI definition object, or an error - */ -export function parse(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function parse(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function parse(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function parse(api: string | OpenAPI.Document): Promise; -export function parse(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function parse(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.* - * - * Parses the given OpenAPI definition file (in JSON or YAML format), and returns it as a JavaScript object. This method `does not` resolve `$ref` pointers or dereference anything. It simply parses one file and returns it. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#parseapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. The path can be absolute or relative. In Node, the path is relative to `process.cwd()`. In the browser, it's relative to the URL of the page. - * @param options (optional) - * @param callback (optional) A callback that will receive the parsed OpenAPI definition object, or an error - */ -export function parse(api: string | OpenAPI.Document, callback: SwaggerParser.ApiCallback): void; -export function parse(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function parse(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.ApiCallback): void; -export function parse(api: string | OpenAPI.Document): Promise; -export function parse(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function parse(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.* - * - * Resolves all JSON references (`$ref` pointers) in the given OpenAPI definition file. If it references any other files/URLs, then they will be downloaded and resolved as well. This method **does not** dereference anything. It simply gives you a `$Refs` object, which is a map of all the resolved references and their values. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#resolveapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive a `$Refs` object - */ -export function resolve(api: string | OpenAPI.Document, callback: SwaggerParser.$RefsCallback): void; -export function resolve(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.$RefsCallback): void; -export function resolve(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.$RefsCallback): void; -export function resolve(api: string | OpenAPI.Document): Promise; -export function resolve(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function resolve(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; - -/** - * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.* - * - * Resolves all JSON references (`$ref` pointers) in the given OpenAPI definition file. If it references any other files/URLs, then they will be downloaded and resolved as well. This method **does not** dereference anything. It simply gives you a `$Refs` object, which is a map of all the resolved references and their values. - * - * See https://apitools.dev/swagger-parser/docs/swagger-parser.html#resolveapi-options-callback - * - * @param api An OpenAPI definition, or the file path or URL of an OpenAPI definition. See the `parse` method for more info. - * @param options (optional) - * @param callback (optional) A callback that will receive a `$Refs` object - */ -export function resolve(api: string | OpenAPI.Document, callback: SwaggerParser.$RefsCallback): void; -export function resolve(api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.$RefsCallback): void; -export function resolve(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options, callback: SwaggerParser.$RefsCallback): void; -export function resolve(api: string | OpenAPI.Document): Promise; -export function resolve(api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; -export function resolve(baseUrl: string, api: string | OpenAPI.Document, options: SwaggerParser.Options): Promise; diff --git a/test/specs/callbacks-promises/callbacks-promises.spec.js b/test/specs/callbacks-promises/callbacks-promises.spec.js index f02faae1..3199d684 100644 --- a/test/specs/callbacks-promises/callbacks-promises.spec.js +++ b/test/specs/callbacks-promises/callbacks-promises.spec.js @@ -20,7 +20,7 @@ describe("Callback & Promise syntax", () => { function testCallbackSuccess (method) { return function (done) { - let parser = new SwaggerParser.SwaggerParser(); + let parser = new SwaggerParser(); parser[method](path.rel("specs/callbacks-promises/callbacks-promises.yaml"), (err, result) => { try { expect(err).to.equal(null); diff --git a/test/specs/typescript-definition.spec.ts b/test/specs/typescript-definition.spec.ts index dd7d6ea3..4023af4f 100644 --- a/test/specs/typescript-definition.spec.ts +++ b/test/specs/typescript-definition.spec.ts @@ -19,7 +19,7 @@ const openapiObject: OpenAPI.Document = { // SwaggerParser class instance -let parser = new SwaggerParser.SwaggerParser(); +let parser = new SwaggerParser(); // SwaggerParser instance properties