oas 19.0.0 → 19.0.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## <small>19.0.2 (2022-10-26)</small>
+
+* fix: quirks with discriminators and the `transformer` JSON Schema option (#698) ([b84c57f](https://github.com/readmeio/oas/commit/b84c57f)), closes [#698](https://github.com/readmeio/oas/issues/698)
+
+
+
+## <small>19.0.1 (2022-10-14)</small>
+
+* feat: supporting transforming a schema object to a primitive (#697) ([048bfc6](https://github.com/readmeio/oas/commit/048bfc6)), closes [#697](https://github.com/readmeio/oas/issues/697)
+
+
+
 ## 19.0.0 (2022-10-10)
 
 * docs: cleaning up some typescript options docs (#696) ([d200fef](https://github.com/readmeio/oas/commit/d200fef)), closes [#696](https://github.com/readmeio/oas/issues/696)

package/dist/lib/openapi-to-json-schema.d.ts

@@ -24,7 +24,7 @@ export declare type toJSONSchemaOptions = {
     /**
      * A function that's called anytime a (circular) `$ref` is found.
      */
-    refLogger?: (ref: string) => void;
+    refLogger?: (ref: string, type: 'ref' | 'discriminator') => void;
     /**
      * A function that's called to potentially transform any discovered schema.
      */

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

@@ -269,7 +269,7 @@ function toJSONSchema(data, opts) {
     // If this schema contains a `$ref`, it's circular and we shouldn't try to resolve it. Just
     // return and move along.
     if (RMOAS.isRef(schema)) {
-        refLogger(schema.$ref);
+        refLogger(schema.$ref, 'ref');
         return transformer({
             $ref: schema.$ref
         });
@@ -345,7 +345,7 @@ function toJSONSchema(data, opts) {
                 // them to the supplied `refLogger`.
                 var mapping_1 = schema.discriminator.mapping;
                 Object.keys(mapping_1).forEach(function (k) {
-                    refLogger(mapping_1[k]);
+                    refLogger(mapping_1[k], 'discriminator');
                 });
             }
         }
@@ -393,7 +393,7 @@ function toJSONSchema(data, opts) {
                     if ('$ref' in example) {
                         // no-op because any `$ref` example here after dereferencing is circular so we should
                         // ignore it
-                        refLogger(example.$ref);
+                        refLogger(example.$ref, 'ref');
                     }
                     else if ('value' in example) {
                         if (isPrimitive(example.value)) {
@@ -446,7 +446,7 @@ function toJSONSchema(data, opts) {
                 if (!Array.isArray(schema.items) && Object.keys(schema.items).length === 1 && RMOAS.isRef(schema.items)) {
                     // `items` contains a `$ref`, so since it's circular we should do a no-op here and log
                     // and ignore it.
-                    refLogger(schema.items.$ref);
+                    refLogger(schema.items.$ref, 'ref');
                 }
                 else if (schema.items !== true) {
                     // Run through the arrays contents and clean them up.

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

@@ -17,6 +17,7 @@ export declare type SchemaWrapper = {
 export declare const types: Record<keyof OASDocument, string>;
 export default function getParametersAsJSONSchema(operation: Operation, api: OASDocument, opts?: {
     globalDefaults?: Record<string, unknown>;
+    includeDiscriminatorMappingRefs?: boolean;
     mergeIntoBodyAndMetadata?: boolean;
     retainDeprecatedProperties?: boolean;
     transformer?: (schema: SchemaObject) => SchemaObject;

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

@@ -61,8 +61,14 @@ exports.types = {
 function getParametersAsJSONSchema(operation, api, opts) {
     var _a;
     var hasCircularRefs = false;
-    function refLogger() {
-        hasCircularRefs = true;
+    var hasDiscriminatorMappingRefs = false;
+    function refLogger(ref, type) {
+        if (type === 'ref') {
+            hasCircularRefs = true;
+        }
+        else {
+            hasDiscriminatorMappingRefs = true;
+        }
     }
     function getDeprecated(schema, type) {
         // If we wish to retain deprecated properties then we shouldn't split them out into the
@@ -109,7 +115,9 @@ function getParametersAsJSONSchema(operation, api, opts) {
         });
         return {
             type: type,
-            schema: __assign(__assign({}, deprecatedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(deprecatedSchema, api) })
+            schema: (0, openapi_to_json_schema_1.isPrimitive)(deprecatedSchema)
+                ? deprecatedSchema
+                : __assign(__assign({}, deprecatedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(deprecatedSchema, api) })
         };
     }
     /**
@@ -152,7 +160,9 @@ function getParametersAsJSONSchema(operation, api, opts) {
         return {
             type: type,
             label: exports.types[type],
-            schema: __assign(__assign({}, cleanedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(cleanedSchema, api) }),
+            schema: (0, openapi_to_json_schema_1.isPrimitive)(cleanedSchema)
+                ? cleanedSchema
+                : __assign(__assign({}, cleanedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(cleanedSchema, api) }),
             deprecatedProps: getDeprecated(cleanedSchema, type)
         };
     }
@@ -210,16 +220,19 @@ function getParametersAsJSONSchema(operation, api, opts) {
                     }
                     if (current.deprecated)
                         currentSchema.deprecated = current.deprecated;
-                    schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
+                    var interimSchema = (0, openapi_to_json_schema_1["default"])(currentSchema, {
                         currentLocation: "/".concat(current.name),
                         globalDefaults: opts.globalDefaults,
                         refLogger: refLogger,
                         transformer: opts.transformer
-                    })), { 
-                        // Note: this applies a $schema version to each field in the larger schema object.
-                        // It's not really *correct* but it's what we have to do because there's a chance that
-                        // the end user has indicated the schemas are different
-                        $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(currentSchema, api) });
+                    });
+                    schema = (0, openapi_to_json_schema_1.isPrimitive)(interimSchema)
+                        ? interimSchema
+                        : __assign(__assign({}, interimSchema), { 
+                            // Note: this applies a `$schema` version to each field in the larger schema
+                            // object. It's not really **correct** but it's what we have to do because
+                            // there's a chance that the end user has indicated the schemas are different.
+                            $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(currentSchema, api) });
                 }
                 else if ('content' in current && typeof current.content === 'object') {
                     var contentKeys = Object.keys(current.content);
@@ -256,16 +269,19 @@ function getParametersAsJSONSchema(operation, api, opts) {
                             }
                             if (current.deprecated)
                                 currentSchema.deprecated = current.deprecated;
-                            schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
+                            var interimSchema = (0, openapi_to_json_schema_1["default"])(currentSchema, {
                                 currentLocation: "/".concat(current.name),
                                 globalDefaults: opts.globalDefaults,
                                 refLogger: refLogger,
                                 transformer: opts.transformer
-                            })), { 
-                                // Note: this applies a $schema version to each field in the larger schema object.
-                                // It's not really *correct* but it's what we have to do because there's a chance
-                                // that the end user has indicated the schemas are different
-                                $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(currentSchema, api) });
+                            });
+                            schema = (0, openapi_to_json_schema_1.isPrimitive)(interimSchema)
+                                ? interimSchema
+                                : __assign(__assign({}, interimSchema), { 
+                                    // Note: this applies a `$schema` version to each field in the larger schema
+                                    // object. It's not really **correct** but it's what we have to do because
+                                    // there's a chance that the end user has indicated the schemas are different.
+                                    $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(currentSchema, api) });
                         }
                     }
                 }
@@ -339,9 +355,13 @@ function getParametersAsJSONSchema(operation, api, opts) {
          *
          * @todo
          */
-        if (hasCircularRefs && components) {
-            // Fixing typing and confused version mismatches
-            group.schema.components = components;
+        if (components) {
+            // We should only include components if we've got circular refs or we have discriminator
+            // mapping refs (we want to include them).
+            if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
+                // Fixing typing and confused version mismatches
+                group.schema.components = components;
+            }
         }
         // Delete deprecatedProps if it's null on the schema.
         if (!group.deprecatedProps)

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

@@ -10,11 +10,7 @@ import type { OASDocument, SchemaObject } from 'rmoas.types';
  * @param statusCode The response status code to generate a schema for.
  */
 export default function getResponseAsJSONSchema(operation: Operation, api: OASDocument, statusCode: string | number, opts?: {
-    /**
-     * With a transformer you can transform any data within a given schema, like say if you want to
-     * rewrite a potentially unsafe `title` that might be eventually used as a JS variable name,
-     * just make sure to return your transformed schema.
-     */
+    includeDiscriminatorMappingRefs?: boolean;
     transformer?: (schema: SchemaObject) => SchemaObject;
 }): {
     type: string | string[];

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

@@ -97,8 +97,14 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
         return null;
     }
     var hasCircularRefs = false;
-    function refLogger() {
-        hasCircularRefs = true;
+    var hasDiscriminatorMappingRefs = false;
+    function refLogger(ref, type) {
+        if (type === 'ref') {
+            hasCircularRefs = true;
+        }
+        else {
+            hasDiscriminatorMappingRefs = true;
+        }
     }
     /**
      * @param content An array of `MediaTypeObject`'s to retrieve a preferred schema out of. We
@@ -139,7 +145,9 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
             // able to render so instead of generating a JSON Schema with an `undefined` type we should
             // default to `string` so there's at least *something* the end-user can interact with.
             type: foundSchema.type || 'string',
-            schema: __assign(__assign({}, schema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(schema, api) }),
+            schema: (0, openapi_to_json_schema_1.isPrimitive)(schema)
+                ? schema
+                : __assign(__assign({}, schema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(schema, api) }),
             label: 'Response body'
         };
         if (response.description && schemaWrapper.schema) {
@@ -152,8 +160,12 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
          *
          * @todo
          */
-        if (hasCircularRefs && api.components && schemaWrapper.schema) {
-            schemaWrapper.schema.components = api.components;
+        if (api.components && schemaWrapper.schema) {
+            // We should only include components if we've got circular refs or we have discriminator
+            // mapping refs (we want to include them).
+            if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
+                schemaWrapper.schema.components = api.components;
+            }
         }
         jsonSchema.push(schemaWrapper);
     }

package/dist/operation.d.ts

@@ -131,6 +131,11 @@ export default class Operation {
          * Contains an object of user defined schema defaults.
          */
         globalDefaults?: Record<string, unknown>;
+        /**
+         * If you wish to include discriminator mapping `$ref` components alongside your
+         * `discriminator` in schemas. Defaults to `true`.
+         */
+        includeDiscriminatorMappingRefs?: boolean;
         /**
          * If you want the output to be two objects: body (contains `body` and `formData` JSON
          * Schema) and metadata (contains `path`, `query`, `cookie`, and `header`).
@@ -154,6 +159,11 @@ export default class Operation {
      * @param statusCode Status code to pull a JSON Schema response for.
      */
     getResponseAsJSONSchema(statusCode: string | number, opts?: {
+        /**
+         * If you wish to include discriminator mapping `$ref` components alongside your
+         * `discriminator` in schemas. Defaults to `true`.
+         */
+        includeDiscriminatorMappingRefs?: boolean;
         /**
          * With a transformer you can transform any data within a given schema, like say if you want
          * to rewrite a potentially unsafe `title` that might be eventually used as a JS variable

package/dist/operation.js

@@ -414,10 +414,7 @@ var Operation = /** @class */ (function () {
      */
     Operation.prototype.getParametersAsJSONSchema = function (opts) {
         if (opts === void 0) { opts = {}; }
-        if (!opts.transformer) {
-            opts.transformer = function (s) { return s; };
-        }
-        return (0, get_parameters_as_json_schema_1["default"])(this, this.api, opts);
+        return (0, get_parameters_as_json_schema_1["default"])(this, this.api, __assign({ includeDiscriminatorMappingRefs: true, transformer: function (s) { return s; } }, opts));
     };
     /**
      * Get a single response for this status code, formatted as JSON schema.
@@ -425,10 +422,8 @@ var Operation = /** @class */ (function () {
      * @param statusCode Status code to pull a JSON Schema response for.
      */
     Operation.prototype.getResponseAsJSONSchema = function (statusCode, opts) {
-        if (opts === void 0) { opts = {
-            transformer: function (s) { return s; }
-        }; }
-        return (0, get_response_as_json_schema_1["default"])(this, this.api, statusCode, opts);
+        if (opts === void 0) { opts = {}; }
+        return (0, get_response_as_json_schema_1["default"])(this, this.api, statusCode, __assign({ includeDiscriminatorMappingRefs: true, transformer: function (s) { return s; } }, opts));
     };
     /**
      * Get an array of all valid response status codes for this operation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "19.0.0",
+  "version": "19.0.2",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",

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

@@ -56,7 +56,7 @@ export type toJSONSchemaOptions = {
   /**
    * A function that's called anytime a (circular) `$ref` is found.
    */
-  refLogger?: (ref: string) => void;
+  refLogger?: (ref: string, type: 'ref' | 'discriminator') => void;
 
   /**
    * A function that's called to potentially transform any discovered schema.
@@ -295,7 +295,7 @@ export default function toJSONSchema(
   // If this schema contains a `$ref`, it's circular and we shouldn't try to resolve it. Just
   // return and move along.
   if (RMOAS.isRef(schema)) {
-    refLogger(schema.$ref);
+    refLogger(schema.$ref, 'ref');
 
     return transformer({
       $ref: schema.$ref,
@@ -381,7 +381,7 @@ export default function toJSONSchema(
         // them to the supplied `refLogger`.
         const mapping = schema.discriminator.mapping;
         Object.keys(mapping).forEach(k => {
-          refLogger(mapping[k]);
+          refLogger(mapping[k], 'discriminator');
         });
       }
     }
@@ -427,7 +427,7 @@ export default function toJSONSchema(
           if ('$ref' in example) {
             // no-op because any `$ref` example here after dereferencing is circular so we should
             // ignore it
-            refLogger(example.$ref);
+            refLogger(example.$ref, 'ref');
           } else if ('value' in example) {
             if (isPrimitive(example.value)) {
               examples.push(example.value);
@@ -480,7 +480,7 @@ export default function toJSONSchema(
         if (!Array.isArray(schema.items) && Object.keys(schema.items).length === 1 && RMOAS.isRef(schema.items)) {
           // `items` contains a `$ref`, so since it's circular we should do a no-op here and log
           // and ignore it.
-          refLogger(schema.items.$ref);
+          refLogger(schema.items.$ref, 'ref');
         } else if (schema.items !== true) {
           // Run through the arrays contents and clean them up.
           schema.items = toJSONSchema(schema.items as RMOAS.SchemaObject, {

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

@@ -4,7 +4,7 @@ import type { OpenAPIV3_1 } from 'openapi-types';
 
 import cloneObject from '../lib/clone-object';
 import matchesMimetype from '../lib/matches-mimetype';
-import toJSONSchema, { getSchemaVersionString } from '../lib/openapi-to-json-schema';
+import toJSONSchema, { isPrimitive, getSchemaVersionString } from '../lib/openapi-to-json-schema';
 
 const isJSON = matchesMimetype.json;
 
@@ -38,15 +38,21 @@ export default function getParametersAsJSONSchema(
   api: OASDocument,
   opts?: {
     globalDefaults?: Record<string, unknown>;
+    includeDiscriminatorMappingRefs?: boolean;
     mergeIntoBodyAndMetadata?: boolean;
     retainDeprecatedProperties?: boolean;
     transformer?: (schema: SchemaObject) => SchemaObject;
   }
 ) {
   let hasCircularRefs = false;
+  let hasDiscriminatorMappingRefs = false;
 
-  function refLogger() {
-    hasCircularRefs = true;
+  function refLogger(ref: string, type: 'ref' | 'discriminator') {
+    if (type === 'ref') {
+      hasCircularRefs = true;
+    } else {
+      hasDiscriminatorMappingRefs = true;
+    }
   }
 
   function getDeprecated(schema: SchemaObject, type: string) {
@@ -102,10 +108,12 @@ export default function getParametersAsJSONSchema(
 
     return {
       type,
-      schema: {
-        ...deprecatedSchema,
-        $schema: getSchemaVersionString(deprecatedSchema, api),
-      },
+      schema: isPrimitive(deprecatedSchema)
+        ? deprecatedSchema
+        : {
+            ...deprecatedSchema,
+            $schema: getSchemaVersionString(deprecatedSchema, api),
+          },
     };
   }
 
@@ -153,10 +161,12 @@ export default function getParametersAsJSONSchema(
     return {
       type,
       label: types[type],
-      schema: {
-        ...cleanedSchema,
-        $schema: getSchemaVersionString(cleanedSchema, api),
-      },
+      schema: isPrimitive(cleanedSchema)
+        ? cleanedSchema
+        : {
+            ...cleanedSchema,
+            $schema: getSchemaVersionString(cleanedSchema, api),
+          },
       deprecatedProps: getDeprecated(cleanedSchema, type),
     };
   }
@@ -224,19 +234,23 @@ export default function getParametersAsJSONSchema(
 
             if (current.deprecated) currentSchema.deprecated = current.deprecated;
 
-            schema = {
-              ...toJSONSchema(currentSchema, {
-                currentLocation: `/${current.name}`,
-                globalDefaults: opts.globalDefaults,
-                refLogger,
-                transformer: opts.transformer,
-              }),
-
-              // Note: this applies a $schema version to each field in the larger schema object.
-              // It's not really *correct* but it's what we have to do because there's a chance that
-              // the end user has indicated the schemas are different
-              $schema: getSchemaVersionString(currentSchema, api),
-            };
+            const interimSchema = toJSONSchema(currentSchema, {
+              currentLocation: `/${current.name}`,
+              globalDefaults: opts.globalDefaults,
+              refLogger,
+              transformer: opts.transformer,
+            });
+
+            schema = isPrimitive(interimSchema)
+              ? interimSchema
+              : {
+                  ...interimSchema,
+
+                  // Note: this applies a `$schema` version to each field in the larger schema
+                  // object. It's not really **correct** but it's what we have to do because
+                  // there's a chance that the end user has indicated the schemas are different.
+                  $schema: getSchemaVersionString(currentSchema, api),
+                };
           } else if ('content' in current && typeof current.content === 'object') {
             const contentKeys = Object.keys(current.content);
             if (contentKeys.length) {
@@ -272,19 +286,23 @@ export default function getParametersAsJSONSchema(
 
                 if (current.deprecated) currentSchema.deprecated = current.deprecated;
 
-                schema = {
-                  ...toJSONSchema(currentSchema, {
-                    currentLocation: `/${current.name}`,
-                    globalDefaults: opts.globalDefaults,
-                    refLogger,
-                    transformer: opts.transformer,
-                  }),
-
-                  // Note: this applies a $schema version to each field in the larger schema object.
-                  // It's not really *correct* but it's what we have to do because there's a chance
-                  // that the end user has indicated the schemas are different
-                  $schema: getSchemaVersionString(currentSchema, api),
-                };
+                const interimSchema = toJSONSchema(currentSchema, {
+                  currentLocation: `/${current.name}`,
+                  globalDefaults: opts.globalDefaults,
+                  refLogger,
+                  transformer: opts.transformer,
+                });
+
+                schema = isPrimitive(interimSchema)
+                  ? interimSchema
+                  : {
+                      ...interimSchema,
+
+                      // Note: this applies a `$schema` version to each field in the larger schema
+                      // object. It's not really **correct** but it's what we have to do because
+                      // there's a chance that the end user has indicated the schemas are different.
+                      $schema: getSchemaVersionString(currentSchema, api),
+                    };
               }
             }
           }
@@ -369,9 +387,13 @@ export default function getParametersAsJSONSchema(
        *
        * @todo
        */
-      if (hasCircularRefs && components) {
-        // Fixing typing and confused version mismatches
-        (group.schema.components as ComponentsObject) = components;
+      if (components) {
+        // We should only include components if we've got circular refs or we have discriminator
+        // mapping refs (we want to include them).
+        if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
+          // Fixing typing and confused version mismatches
+          (group.schema.components as ComponentsObject) = components;
+        }
       }
 
       // Delete deprecatedProps if it's null on the schema.

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

@@ -10,7 +10,7 @@ import type {
 
 import cloneObject from '../lib/clone-object';
 import matches from '../lib/matches-mimetype';
-import toJSONSchema, { getSchemaVersionString } from '../lib/openapi-to-json-schema';
+import toJSONSchema, { isPrimitive, getSchemaVersionString } from '../lib/openapi-to-json-schema';
 
 const isJSON = matches.json;
 
@@ -91,11 +91,7 @@ export default function getResponseAsJSONSchema(
   api: OASDocument,
   statusCode: string | number,
   opts?: {
-    /**
-     * With a transformer you can transform any data within a given schema, like say if you want to
-     * rewrite a potentially unsafe `title` that might be eventually used as a JS variable name,
-     * just make sure to return your transformed schema.
-     */
+    includeDiscriminatorMappingRefs?: boolean;
     transformer?: (schema: SchemaObject) => SchemaObject;
   }
 ) {
@@ -107,9 +103,14 @@ export default function getResponseAsJSONSchema(
   }
 
   let hasCircularRefs = false;
+  let hasDiscriminatorMappingRefs = false;
 
-  function refLogger() {
-    hasCircularRefs = true;
+  function refLogger(ref: string, type: 'ref' | 'discriminator') {
+    if (type === 'ref') {
+      hasCircularRefs = true;
+    } else {
+      hasDiscriminatorMappingRefs = true;
+    }
   }
 
   /**
@@ -160,10 +161,12 @@ export default function getResponseAsJSONSchema(
       // able to render so instead of generating a JSON Schema with an `undefined` type we should
       // default to `string` so there's at least *something* the end-user can interact with.
       type: foundSchema.type || 'string',
-      schema: {
-        ...schema,
-        $schema: getSchemaVersionString(schema, api),
-      },
+      schema: isPrimitive(schema)
+        ? schema
+        : {
+            ...schema,
+            $schema: getSchemaVersionString(schema, api),
+          },
       label: 'Response body',
     };
 
@@ -178,8 +181,12 @@ export default function getResponseAsJSONSchema(
      *
      * @todo
      */
-    if (hasCircularRefs && api.components && schemaWrapper.schema) {
-      ((schemaWrapper.schema as SchemaObject).components as ComponentsObject) = api.components as ComponentsObject;
+    if (api.components && schemaWrapper.schema) {
+      // We should only include components if we've got circular refs or we have discriminator
+      // mapping refs (we want to include them).
+      if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
+        ((schemaWrapper.schema as SchemaObject).components as ComponentsObject) = api.components as ComponentsObject;
+      }
     }
 
     jsonSchema.push(schemaWrapper);

package/src/operation.ts

@@ -465,6 +465,12 @@ export default class Operation {
        */
       globalDefaults?: Record<string, unknown>;
 
+      /**
+       * If you wish to include discriminator mapping `$ref` components alongside your
+       * `discriminator` in schemas. Defaults to `true`.
+       */
+      includeDiscriminatorMappingRefs?: boolean;
+
       /**
        * If you want the output to be two objects: body (contains `body` and `formData` JSON
        * Schema) and metadata (contains `path`, `query`, `cookie`, and `header`).
@@ -485,11 +491,11 @@ export default class Operation {
       transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
     } = {}
   ) {
-    if (!opts.transformer) {
-      opts.transformer = (s: RMOAS.SchemaObject) => s;
-    }
-
-    return getParametersAsJSONSchema(this, this.api, opts);
+    return getParametersAsJSONSchema(this, this.api, {
+      includeDiscriminatorMappingRefs: true,
+      transformer: (s: RMOAS.SchemaObject) => s,
+      ...opts,
+    });
   }
 
   /**
@@ -500,17 +506,25 @@ export default class Operation {
   getResponseAsJSONSchema(
     statusCode: string | number,
     opts: {
+      /**
+       * If you wish to include discriminator mapping `$ref` components alongside your
+       * `discriminator` in schemas. Defaults to `true`.
+       */
+      includeDiscriminatorMappingRefs?: boolean;
+
       /**
        * With a transformer you can transform any data within a given schema, like say if you want
        * to rewrite a potentially unsafe `title` that might be eventually used as a JS variable
        * name, just make sure to return your transformed schema.
        */
       transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
-    } = {
-      transformer: (s: RMOAS.SchemaObject) => s,
-    }
+    } = {}
   ) {
-    return getResponseAsJSONSchema(this, this.api, statusCode, opts);
+    return getResponseAsJSONSchema(this, this.api, statusCode, {
+      includeDiscriminatorMappingRefs: true,
+      transformer: (s: RMOAS.SchemaObject) => s,
+      ...opts,
+    });
   }
 
   /**