oas 18.3.4 → 18.4.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 18.4.0 (2022-08-19)
+
+* feat: porting the library portion of `oas-reducer` into this library (#677) ([f3bc07e](https://github.com/readmeio/oas/commit/f3bc07e)), closes [#677](https://github.com/readmeio/oas/issues/677)
+* chore: stop deleting the `@types/` directory that no longer exists ([98e36fe](https://github.com/readmeio/oas/commit/98e36fe))
+* chore: updating our code standards (#676) ([6b19747](https://github.com/readmeio/oas/commit/6b19747)), closes [#676](https://github.com/readmeio/oas/issues/676)
+* chore(deps-dev): bump @readme/eslint-config from 8.8.3 to 9.0.0 (#675) ([f01f047](https://github.com/readmeio/oas/commit/f01f047)), closes [#675](https://github.com/readmeio/oas/issues/675)
+* chore(deps-dev): bump @readme/oas-examples from 5.4.1 to 5.5.0 (#674) ([d6c0f10](https://github.com/readmeio/oas/commit/d6c0f10)), closes [#674](https://github.com/readmeio/oas/issues/674)
+* chore(deps-dev): bump eslint from 8.20.0 to 8.21.0 (#673) ([0ed3e5c](https://github.com/readmeio/oas/commit/0ed3e5c)), closes [#673](https://github.com/readmeio/oas/issues/673)
+* chore(deps): bump jsonpointer from 5.0.0 to 5.0.1 (#672) ([b6bcdc3](https://github.com/readmeio/oas/commit/b6bcdc3)), closes [#672](https://github.com/readmeio/oas/issues/672)
+
+
+
 ## <small>18.3.4 (2022-07-22)</small>
 
 * chore(deps-dev): bump @commitlint/cli from 16.2.4 to 17.0.2 (#651) ([cedb2da](https://github.com/readmeio/oas/commit/cedb2da)), closes [#651](https://github.com/readmeio/oas/issues/651)

package/dist/index.d.ts

@@ -220,7 +220,8 @@ export default class Oas {
      * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas
      * and circular structures.
      *
-     * @param opts
+     * @param opts Options
+     * @param opts.preserveRefAsJSONSchemaTitle Preserve component schema names within themselves as a `title`.
      */
     dereference(opts?: {
         preserveRefAsJSONSchemaTitle: boolean;

package/dist/index.js

@@ -724,7 +724,8 @@ var Oas = /** @class */ (function () {
      * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas
      * and circular structures.
      *
-     * @param opts
+     * @param opts Options
+     * @param opts.preserveRefAsJSONSchemaTitle Preserve component schema names within themselves as a `title`.
      */
     Oas.prototype.dereference = function (opts) {
         if (opts === void 0) { opts = { preserveRefAsJSONSchemaTitle: false }; }

package/dist/lib/dedupe-common-parameters.d.ts

@@ -3,7 +3,7 @@ import * as RMOAS from '../rmoas.types';
  * With an array of common parameters filter down them to what isn't already present in a list of
  * non-common parameters.
  *
- * @param parameters
- * @param commonParameters
+ * @param parameters Array of parameters defined at the operation level.
+ * @param commonParameters Array of **common** parameters defined at the path item level.
  */
 export default function dedupeCommonParameters(parameters: RMOAS.ParameterObject[], commonParameters: RMOAS.ParameterObject[]): import("openapi-types").OpenAPIV3.ParameterObject[];

package/dist/lib/dedupe-common-parameters.js

@@ -28,8 +28,8 @@ var RMOAS = __importStar(require("../rmoas.types"));
  * With an array of common parameters filter down them to what isn't already present in a list of
  * non-common parameters.
  *
- * @param parameters
- * @param commonParameters
+ * @param parameters Array of parameters defined at the operation level.
+ * @param commonParameters Array of **common** parameters defined at the path item level.
  */
 function dedupeCommonParameters(parameters, commonParameters) {
     return commonParameters.filter(function (param) {

package/dist/lib/openapi-to-json-schema.js

@@ -58,9 +58,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 exports.isPrimitive = exports.getSchemaVersionString = void 0;
-var RMOAS = __importStar(require("../rmoas.types"));
-var jsonpointer_1 = __importDefault(require("jsonpointer"));
 var json_schema_merge_allof_1 = __importDefault(require("json-schema-merge-allof"));
+var jsonpointer_1 = __importDefault(require("jsonpointer"));
+var RMOAS = __importStar(require("../rmoas.types"));
 /**
  * This list has been pulled from `openapi-schema-to-json-schema` but been slightly modified to fit
  * within the constraints in which ReadMe uses the output from this library in schema form
@@ -110,21 +110,23 @@ var FORMAT_OPTIONS = {
  * Encode a string to be used as a JSON pointer.
  *
  * @see {@link https://tools.ietf.org/html/rfc6901}
- * @param str
+ * @param str String to encode into string that can be used as a JSON pointer.
  */
 function encodePointer(str) {
     return str.replace('~', '~0').replace('/', '~1');
 }
 function getSchemaVersionString(schema, api) {
-    // If we're not on version 3.1.0, we always fall back to the default schema version for pre 3.1.0
+    // If we're not on version 3.1.0, we always fall back to the default schema version for pre-3.1.0.
     if (!RMOAS.isOAS31(api)) {
         // This should remain as an HTTP url, not HTTPS.
         return 'http://json-schema.org/draft-04/schema#';
     }
-    // If the schema indicates the version, prefer that.
-    //
-    // We use `as` here because the schema *should* be an OAS 3.1 schema due to the `isOAS31` check
-    // above.
+    /**
+     * If the schema indicates the version, prefer that.
+     *
+     * We use `as` here because the schema *should* be an OAS 3.1 schema due to the `isOAS31` check
+     * above.
+     */
     if (schema.$schema) {
         return schema.$schema;
     }
@@ -142,11 +144,6 @@ exports.isPrimitive = isPrimitive;
 function isPolymorphicSchema(schema) {
     return 'allOf' in schema || 'anyOf' in schema || 'oneOf' in schema;
 }
-/**
- * Determine if a given schema looks like a `requestBody` schema and contains the `content` object.
- *
- * @param schema
- */
 function isRequestBodySchema(schema) {
     return 'content' in schema;
 }
@@ -180,8 +177,8 @@ function isRequestBodySchema(schema) {
  * it shouldn't raise immediate cause for alarm.
  *
  * @see {@link https://tools.ietf.org/html/rfc6901}
- * @param pointer
- * @param examples
+ * @param pointer JSON pointer to search for an example for.
+ * @param examples Array of previous schemas we've found relating to this pointer.
  */
 function searchForExampleByPointer(pointer, examples) {
     if (examples === void 0) { examples = []; }

package/dist/lib/reducer.d.ts

@@ -0,0 +1,24 @@
+import type { OASDocument } from 'rmoas.types';
+export declare type ReducerOptions = {
+    /** A key-value object of path + method combinations to reduce by. */
+    paths?: Record<string, string[] | '*'>;
+    /** An array of tags in the OpenAPI definition to reduce by. */
+    tags?: string[];
+};
+/**
+ * With an array of tags or object of paths+method combinations, reduce an OpenAPI definition to a
+ * new definition that just contains those tags or path + methods.
+ *
+ * @example <caption>Reduce by an array of tags only.</caption>
+ * { APIDEFINITION, { tags: ['pet] } }
+ *
+ * @example <caption>Reduce by a specific path and methods.</caption>
+ * { APIDEFINITION, { paths: { '/pet': ['get', 'post'] } } }
+ *
+ * @example <caption>Reduce by a specific path and all methods it has.</caption>
+ * { APIDEFINITION, { paths: { '/pet': '*' } } }
+ *
+ * @param definition A valid OpenAPI 3.x definition
+ * @param opts Option configuration to reduce by.
+ */
+export default function reducer(definition: OASDocument, opts?: ReducerOptions): OASDocument;

package/dist/lib/reducer.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+var jsonpath_1 = __importDefault(require("jsonpath"));
+var jsonpointer_1 = __importDefault(require("jsonpointer"));
+var utils_1 = require("oas-normalize/dist/lib/utils");
+/**
+ * Query a JSON Schema object for any `$ref` pointers. Return any pointers that were found.
+ *
+ * @param schema JSON Schema object to look for any `$ref` pointers within it.
+ */
+function getUsedRefs(schema) {
+    return jsonpath_1["default"].query(schema, "$..['$ref']");
+}
+/**
+ * Recursively process a `$ref` pointer and accumulate any other `$ref` pointers that it or its
+ * children use.
+ *
+ * @param schema JSON Schema object to look for and accumulate any `$ref` pointers that it may have.
+ * @param $refs Known set of `$ref` pointers.
+ * @param $ref `$ref` pointer to fetch a schema from out of the supplied schema.
+ */
+function accumulateUsedRefs(schema, $refs, $ref) {
+    var $refSchema = jsonpointer_1["default"].get(schema, $ref.substring(1));
+    getUsedRefs($refSchema).forEach(function (currRef) {
+        // If we've already processed this $ref don't send us into an infinite loop.
+        if ($refs.has(currRef)) {
+            return;
+        }
+        $refs.add(currRef);
+        accumulateUsedRefs(schema, $refs, currRef);
+    });
+}
+/**
+ * With an array of tags or object of paths+method combinations, reduce an OpenAPI definition to a
+ * new definition that just contains those tags or path + methods.
+ *
+ * @example <caption>Reduce by an array of tags only.</caption>
+ * { APIDEFINITION, { tags: ['pet] } }
+ *
+ * @example <caption>Reduce by a specific path and methods.</caption>
+ * { APIDEFINITION, { paths: { '/pet': ['get', 'post'] } } }
+ *
+ * @example <caption>Reduce by a specific path and all methods it has.</caption>
+ * { APIDEFINITION, { paths: { '/pet': '*' } } }
+ *
+ * @param definition A valid OpenAPI 3.x definition
+ * @param opts Option configuration to reduce by.
+ */
+function reducer(definition, opts) {
+    if (opts === void 0) { opts = {}; }
+    var reduceTags = 'tags' in opts ? opts.tags : [];
+    var reducePaths = 'paths' in opts ? opts.paths : {};
+    var $refs = new Set();
+    var usedTags = new Set();
+    var baseVersion = parseInt((0, utils_1.version)(definition), 10);
+    if (baseVersion !== 3) {
+        throw new Error('Sorry, only OpenAPI 3.x definitions are supported.');
+    }
+    // Stringify and parse so we get a full non-reference clone of the API definition to work with.
+    var reduced = JSON.parse(JSON.stringify(definition));
+    if ('paths' in reduced) {
+        Object.keys(reduced.paths).forEach(function (path) {
+            if (Object.keys(reducePaths).length) {
+                if (!(path in reducePaths)) {
+                    delete reduced.paths[path];
+                    return;
+                }
+            }
+            Object.keys(reduced.paths[path]).forEach(function (method) {
+                // If this method is `parameters` we should always retain it.
+                if (method !== 'parameters') {
+                    if (Object.keys(reducePaths).length) {
+                        if (reducePaths[path] !== '*' && Array.isArray(reducePaths[path]) && !reducePaths[path].includes(method)) {
+                            delete reduced.paths[path][method];
+                            return;
+                        }
+                    }
+                }
+                var operation = reduced.paths[path][method];
+                // If we're reducing by tags and this operation doesn't live in one of those, remove it.
+                if (reduceTags.length) {
+                    if (!('tags' in operation)) {
+                        delete reduced.paths[path][method];
+                        return;
+                    }
+                    else if (!reduceTags.filter(function (value) { return operation.tags.includes(value); }).length) {
+                        delete reduced.paths[path][method];
+                        return;
+                    }
+                }
+                // Accumulate a list of used tags so we can filter out any ones that we don't need later.
+                if ('tags' in operation) {
+                    operation.tags.forEach(function (tag) {
+                        usedTags.add(tag);
+                    });
+                }
+                // Accumulate a list of $ref pointers that are used within this operation.
+                getUsedRefs(operation).forEach(function (ref) {
+                    $refs.add(ref);
+                });
+                // Accumulate any used security schemas that we need to retain.
+                if ('security' in operation) {
+                    Object.values(operation.security).forEach(function (sec) {
+                        Object.keys(sec).forEach(function (scheme) {
+                            $refs.add("#/components/securitySchemes/".concat(scheme));
+                        });
+                    });
+                }
+            });
+            // If this path no longer has any methods, delete it.
+            if (!Object.keys(reduced.paths[path]).length) {
+                delete reduced.paths[path];
+            }
+        });
+        // If we don't have any more paths after cleanup, throw an error because an OpenAPI file must
+        // have at least one path.
+        if (!Object.keys(reduced.paths).length) {
+            throw new Error('All paths in the API definition were removed. Did you supply the right path name to reduce by?');
+        }
+    }
+    // Recursively accumulate any components that are in use.
+    $refs.forEach(function ($ref) { return accumulateUsedRefs(reduced, $refs, $ref); });
+    // Remove any unused components.
+    if ('components' in reduced) {
+        Object.keys(reduced.components).forEach(function (componentType) {
+            Object.keys(reduced.components[componentType]).forEach(function (component) {
+                if (!$refs.has("#/components/".concat(componentType, "/").concat(component))) {
+                    delete reduced.components[componentType][component];
+                }
+            });
+            // If this component group is now empty, delete it.
+            if (!Object.keys(reduced.components[componentType]).length) {
+                delete reduced.components[componentType];
+            }
+        });
+        // If this path no longer has any components, delete it.
+        if (!Object.keys(reduced.components).length) {
+            delete reduced.components;
+        }
+    }
+    // Remove any unused tags.
+    if ('tags' in reduced) {
+        reduced.tags.forEach(function (tag, k) {
+            if (!usedTags.has(tag.name)) {
+                delete reduced.tags[k];
+            }
+        });
+        // Remove any now empty items from the tags array.
+        reduced.tags = reduced.tags.filter(Boolean);
+        if (!reduced.tags.length) {
+            delete reduced.tags;
+        }
+    }
+    return reduced;
+}
+exports["default"] = reducer;

package/dist/operation/get-parameters-as-json-schema.d.ts

@@ -1,5 +1,5 @@
-import type { OASDocument, SchemaObject } from '../rmoas.types';
 import type Operation from '../operation';
+import type { OASDocument, SchemaObject } from '../rmoas.types';
 export declare type SchemaWrapper = {
     $schema?: string;
     type: string;

package/dist/operation/get-parameters-as-json-schema.js

@@ -38,9 +38,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 exports.types = void 0;
+var clone_object_1 = __importDefault(require("../lib/clone-object"));
 var matches_mimetype_1 = __importDefault(require("../lib/matches-mimetype"));
 var openapi_to_json_schema_1 = __importStar(require("../lib/openapi-to-json-schema"));
-var clone_object_1 = __importDefault(require("../lib/clone-object"));
 var isJSON = matches_mimetype_1["default"].json;
 /**
  * The order of this object determines how they will be sorted in the compiled JSON Schema
@@ -161,7 +161,8 @@ function getParametersAsJsonSchema(operation, api, opts) {
                  * Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large
                  * variety of types that that object could represent but I can't yet think of a way to get
                  * around that.
-                 * @fixme
+                 *
+                 * @todo
                  */
                 components[componentType] = {};
                 Object.keys(api.components[componentType]).forEach(function (schemaName) {
@@ -326,6 +327,7 @@ function getParametersAsJsonSchema(operation, api, opts) {
          * Since this library assumes that the schema has already been dereferenced, adding every
          * component here that **isn't** circular adds a ton of bloat so it'd be cool if `components`
          * was just the remaining `$ref` pointers that are still being referenced.
+         *
          * @todo
          */
         if (hasCircularRefs && components) {

package/dist/operation/get-response-as-json-schema.d.ts

@@ -1,5 +1,5 @@
-import type { OASDocument, SchemaObject } from 'rmoas.types';
 import type Operation from 'operation';
+import type { OASDocument, SchemaObject } from 'rmoas.types';
 /**
  * Extract all the response schemas, matching the format of get-parameters-as-json-schema.
  *

package/dist/operation/get-response-as-json-schema.js

@@ -37,9 +37,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-var openapi_to_json_schema_1 = __importStar(require("../lib/openapi-to-json-schema"));
-var matches_mimetype_1 = __importDefault(require("../lib/matches-mimetype"));
 var clone_object_1 = __importDefault(require("../lib/clone-object"));
+var matches_mimetype_1 = __importDefault(require("../lib/matches-mimetype"));
+var openapi_to_json_schema_1 = __importStar(require("../lib/openapi-to-json-schema"));
 var isJSON = matches_mimetype_1["default"].json;
 /**
  * Turn a header map from OpenAPI 3.0.3 (and some earlier versions too) into a schema.
@@ -138,6 +138,7 @@ function getResponseAsJsonSchema(operation, api, statusCode) {
          * Since this library assumes that the schema has already been dereferenced, adding every
          * component here that **isn't** circular adds a ton of bloat so it'd be cool if `components`
          * was just the remaining `$ref` pointers that are still being referenced.
+         *
          * @todo
          */
         if (hasCircularRefs && api.components && schemaWrapper.schema) {

package/dist/operation/get-response-examples.js

@@ -14,8 +14,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-var rmoas_types_1 = require("../rmoas.types");
 var get_mediatype_examples_1 = __importDefault(require("../lib/get-mediatype-examples"));
+var rmoas_types_1 = require("../rmoas.types");
 /**
  * Retrieve a collection of response examples keyed, by their media type.
  *

package/dist/operation.d.ts

@@ -1,5 +1,5 @@
-import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { CallbackExamples } from './operation/get-callback-examples';
+import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
 import * as RMOAS from './rmoas.types';
 declare type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
@@ -89,7 +89,7 @@ export default class Operation {
      * 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.
      *
-     * @param opts
+     * @param opts Options
      * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
     getOperationId(opts?: {
@@ -124,7 +124,7 @@ export default class Operation {
      * Convert the operation into an array of JSON Schema schemas for each available type of
      * parameter available on the operation.
      *
-     * @param opts
+     * @param opts Options
      * @param opts.globalDefaults Contains an object of user defined schema defaults.
      * @param opts.mergeIntoBodyAndMetadata If you want the output to be two objects: body (contains
      *    `body` and `formData` JSON Schema) and metadata (contains `path`, `query`, `cookie`, and
@@ -140,7 +140,7 @@ export default class Operation {
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
-     * @param statusCode
+     * @param statusCode Status code to pull a JSON Schema response for.
      */
     getResponseAsJsonSchema(statusCode: string | number): {
         type: string | string[];
@@ -191,7 +191,7 @@ export default class Operation {
     /**
      * Return a specific response out of the operation by a given HTTP status code.
      *
-     * @param statusCode
+     * @param statusCode Status code to pull a response object for.
      */
     getResponseByStatusCode(statusCode: string | number): boolean | RMOAS.ResponseObject;
     /**

package/dist/operation.js

@@ -53,15 +53,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 exports.Webhook = exports.Callback = void 0;
-var RMOAS = __importStar(require("./rmoas.types"));
 var dedupe_common_parameters_1 = __importDefault(require("./lib/dedupe-common-parameters"));
 var find_schema_definition_1 = __importDefault(require("./lib/find-schema-definition"));
+var matches_mimetype_1 = __importDefault(require("./lib/matches-mimetype"));
+var get_callback_examples_1 = __importDefault(require("./operation/get-callback-examples"));
 var get_parameters_as_json_schema_1 = __importDefault(require("./operation/get-parameters-as-json-schema"));
-var get_response_as_json_schema_1 = __importDefault(require("./operation/get-response-as-json-schema"));
 var get_requestbody_examples_1 = __importDefault(require("./operation/get-requestbody-examples"));
-var get_callback_examples_1 = __importDefault(require("./operation/get-callback-examples"));
+var get_response_as_json_schema_1 = __importDefault(require("./operation/get-response-as-json-schema"));
 var get_response_examples_1 = __importDefault(require("./operation/get-response-examples"));
-var matches_mimetype_1 = __importDefault(require("./lib/matches-mimetype"));
+var RMOAS = __importStar(require("./rmoas.types"));
 var utils_1 = require("./utils");
 var Operation = /** @class */ (function () {
     function Operation(api, path, method, operation) {
@@ -304,7 +304,7 @@ var Operation = /** @class */ (function () {
      * 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.
      *
-     * @param opts
+     * @param opts Options
      * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
     Operation.prototype.getOperationId = function (opts) {
@@ -408,7 +408,7 @@ var Operation = /** @class */ (function () {
      * Convert the operation into an array of JSON Schema schemas for each available type of
      * parameter available on the operation.
      *
-     * @param opts
+     * @param opts Options
      * @param opts.globalDefaults Contains an object of user defined schema defaults.
      * @param opts.mergeIntoBodyAndMetadata If you want the output to be two objects: body (contains
      *    `body` and `formData` JSON Schema) and metadata (contains `path`, `query`, `cookie`, and
@@ -423,7 +423,7 @@ var Operation = /** @class */ (function () {
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
-     * @param statusCode
+     * @param statusCode Status code to pull a JSON Schema response for.
      */
     Operation.prototype.getResponseAsJsonSchema = function (statusCode) {
         return (0, get_response_as_json_schema_1["default"])(this, this.api, statusCode);
@@ -550,7 +550,7 @@ var Operation = /** @class */ (function () {
     /**
      * Return a specific response out of the operation by a given HTTP status code.
      *
-     * @param statusCode
+     * @param statusCode Status code to pull a response object for.
      */
     Operation.prototype.getResponseByStatusCode = function (statusCode) {
         if (!this.schema.responses) {

package/dist/rmoas.types.d.ts

@@ -1,5 +1,5 @@
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import type { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 export declare type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 /**
  * @param check Data to determine if it contains a ReferenceObject (`$ref` pointer`).

package/dist/samples/index.js

@@ -3,9 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-var utils_1 = require("./utils");
-var memoizee_1 = __importDefault(require("memoizee"));
 var json_schema_merge_allof_1 = __importDefault(require("json-schema-merge-allof"));
+var memoizee_1 = __importDefault(require("memoizee"));
+var utils_1 = require("./utils");
 var sampleDefaults = function (genericSample) {
     return function (schema) {
         return typeof schema["default"] === typeof genericSample ? schema["default"] : genericSample;

package/dist/samples/utils.d.ts

@@ -5,7 +5,7 @@
  * @see {@link https://github.com/swagger-api/swagger-ui/blob/master/src/core/utils.js}
  */
 import type * as RMOAS from '../rmoas.types';
-export declare function usesPolymorphism(schema: RMOAS.SchemaObject): false | "oneOf" | "anyOf" | "allOf";
+export declare function usesPolymorphism(schema: RMOAS.SchemaObject): false | "anyOf" | "oneOf" | "allOf";
 export declare function objectify(thing: unknown | Record<string, unknown>): Record<string, any>;
 export declare function normalizeArray(arr: string | number | (string | number)[]): (string | number)[];
 export declare function isFunc(thing: unknown): thing is Function;

package/dist/samples/utils.js

@@ -1,10 +1,4 @@
 "use strict";
-/**
- * Portions of this file have been extracted and modified from Swagger UI.
- *
- * @license Apache-2.0
- * @see {@link https://github.com/swagger-api/swagger-ui/blob/master/src/core/utils.js}
- */
 var __assign = (this && this.__assign) || function () {
     __assign = Object.assign || function(t) {
         for (var s, i = 1, n = arguments.length; i < n; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "18.3.4",
+  "version": "18.4.0",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -37,7 +37,7 @@
   "scripts": {
     "build": "tsc",
     "lint": "eslint . --ext .js,.ts",
-    "prebuild": "rm -rf dist/ @types/",
+    "prebuild": "rm -rf dist/",
     "prepack": "npm run build",
     "prepare": "husky install",
     "pretest": "npm run lint",
@@ -56,10 +56,11 @@
     "inquirer": "^8.1.2",
     "json-schema-merge-allof": "^0.8.1",
     "json2yaml": "^1.1.0",
+    "jsonpath": "^1.1.1",
     "jsonpointer": "^5.0.0",
     "memoizee": "^0.4.14",
     "minimist": "^1.2.0",
-    "oas-normalize": "^6.0.0",
+    "oas-normalize": "^7.0.0",
     "openapi-types": "^12.0.0",
     "path-to-regexp": "^6.2.0",
     "swagger-inline": "^6.0.0"
@@ -67,11 +68,12 @@
   "devDependencies": {
     "@commitlint/cli": "^17.0.2",
     "@commitlint/config-conventional": "^17.0.2",
-    "@readme/eslint-config": "^8.8.3",
+    "@readme/eslint-config": "^10.0.0",
     "@readme/oas-examples": "^5.4.1",
     "@readme/openapi-parser": "^2.2.0",
     "@types/jest": "^28.1.6",
     "@types/json-schema-merge-allof": "^0.6.1",
+    "@types/jsonpath": "^0.2.0",
     "@types/memoizee": "^0.4.6",
     "eslint": "^8.20.0",
     "husky": "^8.0.1",

package/src/cli/commands/endpoint.js

@@ -1,4 +1,5 @@
 const chalk = require('chalk');
+
 const utils = require('../lib/utils');
 
 exports.swagger = false;

package/src/cli/commands/help.js

@@ -1,6 +1,7 @@
+const path = require('path');
+
 const chalk = require('chalk');
 const glob = require('glob');
-const path = require('path');
 
 exports.swagger = false;
 exports.desc = 'Learn what you can do with oas';

package/src/cli/commands/init.js

@@ -1,8 +1,10 @@
-const chalk = require('chalk');
+const fs = require('fs');
 const path = require('path');
+
+const chalk = require('chalk');
 const inquirer = require('inquirer');
-const fs = require('fs');
 const YAML = require('json2yaml');
+
 const utils = require('../lib/utils');
 
 exports.swagger = false;

package/src/cli/index.js

@@ -1,5 +1,7 @@
-const chalk = require('chalk');
 const path = require('path');
+
+const chalk = require('chalk');
+
 const utils = require('./lib/utils');
 
 function loadAction(action = 'help') {

package/src/cli/lib/utils.js

@@ -1,9 +1,10 @@
-const chalk = require('chalk');
 const fs = require('fs');
+
 const cardinal = require('cardinal');
+const chalk = require('chalk');
 const glob = require('glob');
-const swaggerInline = require('swagger-inline');
 const OASNormalize = require('oas-normalize');
+const swaggerInline = require('swagger-inline');
 
 exports.findSwagger = async function (info, cb) {
   const file = info.args[info.args.length - 1];

package/src/index.ts

@@ -4,6 +4,7 @@ import type { MatchResult } from 'path-to-regexp';
 
 import $RefParser from '@readme/json-schema-ref-parser';
 import { pathToRegexp, match } from 'path-to-regexp';
+
 import getAuth from './lib/get-auth';
 import getUserVariable from './lib/get-user-variable';
 import Operation, { Callback, Webhook } from './operation';
@@ -757,7 +758,8 @@ export default class Oas {
    * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas
    * and circular structures.
    *
-   * @param opts
+   * @param opts Options
+   * @param opts.preserveRefAsJSONSchemaTitle Preserve component schema names within themselves as a `title`.
    */
   async dereference(opts = { preserveRefAsJSONSchemaTitle: false }) {
     if (this.dereferencing.complete) {

package/src/lib/dedupe-common-parameters.ts

@@ -4,8 +4,8 @@ import * as RMOAS from '../rmoas.types';
  * With an array of common parameters filter down them to what isn't already present in a list of
  * non-common parameters.
  *
- * @param parameters
- * @param commonParameters
+ * @param parameters Array of parameters defined at the operation level.
+ * @param commonParameters Array of **common** parameters defined at the path item level.
  */
 export default function dedupeCommonParameters(
   parameters: RMOAS.ParameterObject[],

package/src/lib/get-mediatype-examples.ts

@@ -1,5 +1,7 @@
 import type * as RMOAS from '../rmoas.types';
+
 import sampleFromSchema from '../samples';
+
 import matchesMimeType from './matches-mimetype';
 
 export type MediaTypeExample = {

package/src/lib/openapi-to-json-schema.ts

@@ -1,8 +1,10 @@
 /* eslint-disable no-continue */
 import type { OpenAPIV3_1 } from 'openapi-types';
-import * as RMOAS from '../rmoas.types';
-import jsonpointer from 'jsonpointer';
+
 import mergeJSONSchemaAllOf from 'json-schema-merge-allof';
+import jsonpointer from 'jsonpointer';
+
+import * as RMOAS from '../rmoas.types';
 
 /**
  * This list has been pulled from `openapi-schema-to-json-schema` but been slightly modified to fit
@@ -72,23 +74,25 @@ const FORMAT_OPTIONS: {
  * Encode a string to be used as a JSON pointer.
  *
  * @see {@link https://tools.ietf.org/html/rfc6901}
- * @param str
+ * @param str String to encode into string that can be used as a JSON pointer.
  */
 function encodePointer(str: string) {
   return str.replace('~', '~0').replace('/', '~1');
 }
 
 export function getSchemaVersionString(schema: RMOAS.SchemaObject, api: RMOAS.OASDocument): string {
-  // If we're not on version 3.1.0, we always fall back to the default schema version for pre 3.1.0
+  // If we're not on version 3.1.0, we always fall back to the default schema version for pre-3.1.0.
   if (!RMOAS.isOAS31(api)) {
     // This should remain as an HTTP url, not HTTPS.
     return 'http://json-schema.org/draft-04/schema#';
   }
 
-  // If the schema indicates the version, prefer that.
-  //
-  // We use `as` here because the schema *should* be an OAS 3.1 schema due to the `isOAS31` check
-  // above.
+  /**
+   * If the schema indicates the version, prefer that.
+   *
+   * We use `as` here because the schema *should* be an OAS 3.1 schema due to the `isOAS31` check
+   * above.
+   */
   if ((schema as OpenAPIV3_1.SchemaObject).$schema) {
     return (schema as OpenAPIV3_1.SchemaObject).$schema;
   }
@@ -109,11 +113,6 @@ function isPolymorphicSchema(schema: RMOAS.SchemaObject): boolean {
   return 'allOf' in schema || 'anyOf' in schema || 'oneOf' in schema;
 }
 
-/**
- * Determine if a given schema looks like a `requestBody` schema and contains the `content` object.
- *
- * @param schema
- */
 function isRequestBodySchema(schema: unknown): schema is RMOAS.RequestBodyObject {
   return 'content' in (schema as RMOAS.RequestBodyObject);
 }
@@ -148,8 +147,8 @@ function isRequestBodySchema(schema: unknown): schema is RMOAS.RequestBodyObject
  * it shouldn't raise immediate cause for alarm.
  *
  * @see {@link https://tools.ietf.org/html/rfc6901}
- * @param pointer
- * @param examples
+ * @param pointer JSON pointer to search for an example for.
+ * @param examples Array of previous schemas we've found relating to this pointer.
  */
 function searchForExampleByPointer(pointer: string, examples: PrevSchemasType = []) {
   if (!examples.length || !pointer.length) {

package/src/lib/reducer.ts

@@ -0,0 +1,184 @@
+import type { ComponentsObject, HttpMethods, OASDocument, TagObject } from 'rmoas.types';
+
+import jsonPath from 'jsonpath';
+import jsonPointer from 'jsonpointer';
+import { version as getAPIDefinitionVersion } from 'oas-normalize/dist/lib/utils';
+
+export type ReducerOptions = {
+  /** A key-value object of path + method combinations to reduce by. */
+  paths?: Record<string, string[] | '*'>;
+  /** An array of tags in the OpenAPI definition to reduce by. */
+  tags?: string[];
+};
+
+/**
+ * Query a JSON Schema object for any `$ref` pointers. Return any pointers that were found.
+ *
+ * @param schema JSON Schema object to look for any `$ref` pointers within it.
+ */
+function getUsedRefs(schema: any) {
+  return jsonPath.query(schema, "$..['$ref']");
+}
+
+/**
+ * Recursively process a `$ref` pointer and accumulate any other `$ref` pointers that it or its
+ * children use.
+ *
+ * @param schema JSON Schema object to look for and accumulate any `$ref` pointers that it may have.
+ * @param $refs Known set of `$ref` pointers.
+ * @param $ref `$ref` pointer to fetch a schema from out of the supplied schema.
+ */
+function accumulateUsedRefs(schema: Record<string, unknown>, $refs: Set<string>, $ref: string): void {
+  const $refSchema = jsonPointer.get(schema, $ref.substring(1));
+  getUsedRefs($refSchema).forEach(currRef => {
+    // If we've already processed this $ref don't send us into an infinite loop.
+    if ($refs.has(currRef)) {
+      return;
+    }
+
+    $refs.add(currRef);
+    accumulateUsedRefs(schema, $refs, currRef);
+  });
+}
+
+/**
+ * With an array of tags or object of paths+method combinations, reduce an OpenAPI definition to a
+ * new definition that just contains those tags or path + methods.
+ *
+ * @example <caption>Reduce by an array of tags only.</caption>
+ * { APIDEFINITION, { tags: ['pet] } }
+ *
+ * @example <caption>Reduce by a specific path and methods.</caption>
+ * { APIDEFINITION, { paths: { '/pet': ['get', 'post'] } } }
+ *
+ * @example <caption>Reduce by a specific path and all methods it has.</caption>
+ * { APIDEFINITION, { paths: { '/pet': '*' } } }
+ *
+ * @param definition A valid OpenAPI 3.x definition
+ * @param opts Option configuration to reduce by.
+ */
+export default function reducer(definition: OASDocument, opts: ReducerOptions = {}) {
+  const reduceTags = 'tags' in opts ? opts.tags : [];
+  const reducePaths = 'paths' in opts ? opts.paths : {};
+
+  const $refs: Set<string> = new Set();
+  const usedTags: Set<string> = new Set();
+
+  const baseVersion = parseInt(getAPIDefinitionVersion(definition as any), 10);
+  if (baseVersion !== 3) {
+    throw new Error('Sorry, only OpenAPI 3.x definitions are supported.');
+  }
+
+  // Stringify and parse so we get a full non-reference clone of the API definition to work with.
+  const reduced = JSON.parse(JSON.stringify(definition)) as OASDocument;
+
+  if ('paths' in reduced) {
+    Object.keys(reduced.paths).forEach(path => {
+      if (Object.keys(reducePaths).length) {
+        if (!(path in reducePaths)) {
+          delete reduced.paths[path];
+          return;
+        }
+      }
+
+      Object.keys(reduced.paths[path]).forEach((method: 'parameters' | HttpMethods) => {
+        // If this method is `parameters` we should always retain it.
+        if (method !== 'parameters') {
+          if (Object.keys(reducePaths).length) {
+            if (reducePaths[path] !== '*' && Array.isArray(reducePaths[path]) && !reducePaths[path].includes(method)) {
+              delete reduced.paths[path][method];
+              return;
+            }
+          }
+        }
+
+        const operation = reduced.paths[path][method];
+
+        // If we're reducing by tags and this operation doesn't live in one of those, remove it.
+        if (reduceTags.length) {
+          if (!('tags' in operation)) {
+            delete reduced.paths[path][method];
+            return;
+          } else if (!reduceTags.filter(value => operation.tags.includes(value)).length) {
+            delete reduced.paths[path][method];
+            return;
+          }
+        }
+
+        // Accumulate a list of used tags so we can filter out any ones that we don't need later.
+        if ('tags' in operation) {
+          operation.tags.forEach((tag: string) => {
+            usedTags.add(tag);
+          });
+        }
+
+        // Accumulate a list of $ref pointers that are used within this operation.
+        getUsedRefs(operation).forEach(ref => {
+          $refs.add(ref);
+        });
+
+        // Accumulate any used security schemas that we need to retain.
+        if ('security' in operation) {
+          Object.values(operation.security).forEach(sec => {
+            Object.keys(sec).forEach(scheme => {
+              $refs.add(`#/components/securitySchemes/${scheme}`);
+            });
+          });
+        }
+      });
+
+      // If this path no longer has any methods, delete it.
+      if (!Object.keys(reduced.paths[path]).length) {
+        delete reduced.paths[path];
+      }
+    });
+
+    // If we don't have any more paths after cleanup, throw an error because an OpenAPI file must
+    // have at least one path.
+    if (!Object.keys(reduced.paths).length) {
+      throw new Error('All paths in the API definition were removed. Did you supply the right path name to reduce by?');
+    }
+  }
+
+  // Recursively accumulate any components that are in use.
+  $refs.forEach($ref => accumulateUsedRefs(reduced, $refs, $ref));
+
+  // Remove any unused components.
+  if ('components' in reduced) {
+    Object.keys(reduced.components).forEach((componentType: keyof ComponentsObject) => {
+      Object.keys(reduced.components[componentType]).forEach(component => {
+        if (!$refs.has(`#/components/${componentType}/${component}`)) {
+          delete reduced.components[componentType][component];
+        }
+      });
+
+      // If this component group is now empty, delete it.
+      if (!Object.keys(reduced.components[componentType]).length) {
+        delete reduced.components[componentType];
+      }
+    });
+
+    // If this path no longer has any components, delete it.
+    if (!Object.keys(reduced.components).length) {
+      delete reduced.components;
+    }
+  }
+
+  // Remove any unused tags.
+  if ('tags' in reduced) {
+    reduced.tags.forEach((tag: TagObject, k: number) => {
+      if (!usedTags.has(tag.name)) {
+        delete reduced.tags[k];
+      }
+    });
+
+    // Remove any now empty items from the tags array.
+    reduced.tags = reduced.tags.filter(Boolean);
+
+    if (!reduced.tags.length) {
+      delete reduced.tags;
+    }
+  }
+
+  return reduced;
+}

package/src/operation/get-callback-examples.ts

@@ -1,4 +1,5 @@
 import type * as RMOAS from '../rmoas.types';
+
 import getResponseExamples from './get-response-examples';
 
 export type CallbackExamples = {

package/src/operation/get-parameters-as-json-schema.ts

@@ -1,9 +1,10 @@
+import type Operation from '../operation';
 import type { ComponentsObject, ExampleObject, OASDocument, ParameterObject, SchemaObject } from '../rmoas.types';
 import type { OpenAPIV3_1 } from 'openapi-types';
-import type Operation from '../operation';
+
+import cloneObject from '../lib/clone-object';
 import matchesMimetype from '../lib/matches-mimetype';
 import toJSONSchema, { getSchemaVersionString } from '../lib/openapi-to-json-schema';
-import cloneObject from '../lib/clone-object';
 
 const isJSON = matchesMimetype.json;
 
@@ -166,7 +167,8 @@ export default function getParametersAsJsonSchema(
          * Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large
          * variety of types that that object could represent but I can't yet think of a way to get
          * around that.
-         * @fixme
+         *
+         * @todo
          */
         components[componentType] = {};
 
@@ -354,6 +356,7 @@ export default function getParametersAsJsonSchema(
        * Since this library assumes that the schema has already been dereferenced, adding every
        * component here that **isn't** circular adds a ton of bloat so it'd be cool if `components`
        * was just the remaining `$ref` pointers that are still being referenced.
+       *
        * @todo
        */
       if (hasCircularRefs && components) {

package/src/operation/get-requestbody-examples.ts

@@ -1,4 +1,5 @@
 import type * as RMOAS from '../rmoas.types';
+
 import getMediaTypeExamples from '../lib/get-mediatype-examples';
 
 export type RequestBodyExamples = {

package/src/operation/get-response-as-json-schema.ts

@@ -1,3 +1,4 @@
+import type Operation from 'operation';
 import type {
   ComponentsObject,
   MediaTypeObject,
@@ -6,10 +7,10 @@ import type {
   SchemaObject,
   HeaderObject,
 } from 'rmoas.types';
-import type Operation from 'operation';
-import toJSONSchema, { getSchemaVersionString } from '../lib/openapi-to-json-schema';
-import matches from '../lib/matches-mimetype';
+
 import cloneObject from '../lib/clone-object';
+import matches from '../lib/matches-mimetype';
+import toJSONSchema, { getSchemaVersionString } from '../lib/openapi-to-json-schema';
 
 const isJSON = matches.json;
 
@@ -141,6 +142,7 @@ export default function getResponseAsJsonSchema(operation: Operation, api: OASDo
      * Since this library assumes that the schema has already been dereferenced, adding every
      * component here that **isn't** circular adds a ton of bloat so it'd be cool if `components`
      * was just the remaining `$ref` pointers that are still being referenced.
+     *
      * @todo
      */
     if (hasCircularRefs && api.components && schemaWrapper.schema) {

package/src/operation/get-response-examples.ts

@@ -1,8 +1,8 @@
-import type * as RMOAS from '../rmoas.types';
 import type { MediaTypeExample } from '../lib/get-mediatype-examples';
+import type * as RMOAS from '../rmoas.types';
 
-import { isRef } from '../rmoas.types';
 import getMediaTypeExamples from '../lib/get-mediatype-examples';
+import { isRef } from '../rmoas.types';
 
 export type ResponseExamples = {
   status: string;

package/src/operation.ts

@@ -1,17 +1,17 @@
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { CallbackExamples } from './operation/get-callback-examples';
+import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 
-import * as RMOAS from './rmoas.types';
 import dedupeCommonParameters from './lib/dedupe-common-parameters';
 import findSchemaDefinition from './lib/find-schema-definition';
+import matchesMimeType from './lib/matches-mimetype';
+import getCallbackExamples from './operation/get-callback-examples';
 import getParametersAsJsonSchema from './operation/get-parameters-as-json-schema';
-import getResponseAsJsonSchema from './operation/get-response-as-json-schema';
 import getRequestBodyExamples from './operation/get-requestbody-examples';
-import getCallbackExamples from './operation/get-callback-examples';
+import getResponseAsJsonSchema from './operation/get-response-as-json-schema';
 import getResponseExamples from './operation/get-response-examples';
-import matchesMimeType from './lib/matches-mimetype';
+import * as RMOAS from './rmoas.types';
 import { supportedMethods } from './utils';
 
 type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
@@ -332,7 +332,7 @@ export default class Operation {
    * 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.
    *
-   * @param opts
+   * @param opts Options
    * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
    */
   getOperationId(opts?: { camelCase: boolean }): string {
@@ -448,7 +448,7 @@ export default class Operation {
    * Convert the operation into an array of JSON Schema schemas for each available type of
    * parameter available on the operation.
    *
-   * @param opts
+   * @param opts Options
    * @param opts.globalDefaults Contains an object of user defined schema defaults.
    * @param opts.mergeIntoBodyAndMetadata If you want the output to be two objects: body (contains
    *    `body` and `formData` JSON Schema) and metadata (contains `path`, `query`, `cookie`, and
@@ -469,7 +469,7 @@ export default class Operation {
   /**
    * Get a single response for this status code, formatted as JSON schema.
    *
-   * @param statusCode
+   * @param statusCode Status code to pull a JSON Schema response for.
    */
   getResponseAsJsonSchema(statusCode: string | number) {
     return getResponseAsJsonSchema(this, this.api, statusCode);
@@ -616,7 +616,7 @@ export default class Operation {
   /**
    * Return a specific response out of the operation by a given HTTP status code.
    *
-   * @param statusCode
+   * @param statusCode Status code to pull a response object for.
    */
   getResponseByStatusCode(statusCode: string | number): boolean | RMOAS.ResponseObject {
     if (!this.schema.responses) {

package/src/rmoas.types.ts

@@ -1,5 +1,5 @@
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import type { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 
 export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 

package/src/samples/index.ts

@@ -5,9 +5,11 @@
  * @see {@link https://github.com/swagger-api/swagger-ui/blob/master/src/core/plugins/samples/fn.js}
  */
 import type * as RMOAS from '../rmoas.types';
-import { objectify, usesPolymorphism, isFunc, normalizeArray, deeplyStripKey } from './utils';
-import memoize from 'memoizee';
+
 import mergeAllOf from 'json-schema-merge-allof';
+import memoize from 'memoizee';
+
+import { objectify, usesPolymorphism, isFunc, normalizeArray, deeplyStripKey } from './utils';
 
 const sampleDefaults = (genericSample: string | number | boolean) => {
   return (schema: RMOAS.SchemaObject): typeof genericSample =>

package/src/samples/utils.ts

@@ -4,7 +4,6 @@
  * @license Apache-2.0
  * @see {@link https://github.com/swagger-api/swagger-ui/blob/master/src/core/utils.js}
  */
-
 import type * as RMOAS from '../rmoas.types';
 
 function isObject(obj: unknown) {