oas 18.4.4 → 19.0.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "js/ts.implicitProjectConfig.strictNullChecks": false
+}

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 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)
+* feat: addition of a new JSON Schema transformer option + operationId fixes (#695) ([5609230](https://github.com/readmeio/oas/commit/5609230)), closes [#695](https://github.com/readmeio/oas/issues/695)
+* chore(deps-dev): bump @commitlint/cli from 17.0.3 to 17.1.2 (#682) ([aacfcf9](https://github.com/readmeio/oas/commit/aacfcf9)), closes [#682](https://github.com/readmeio/oas/issues/682)
+* chore(deps-dev): bump @commitlint/config-conventional (#685) ([4e928c0](https://github.com/readmeio/oas/commit/4e928c0)), closes [#685](https://github.com/readmeio/oas/issues/685)
+* chore(deps-dev): bump @readme/eslint-config from 10.0.0 to 10.1.0 (#686) ([e008c85](https://github.com/readmeio/oas/commit/e008c85)), closes [#686](https://github.com/readmeio/oas/issues/686)
+* chore(deps-dev): bump @readme/oas-examples from 5.5.0 to 5.6.0 (#684) ([2fa542e](https://github.com/readmeio/oas/commit/2fa542e)), closes [#684](https://github.com/readmeio/oas/issues/684)
+* chore(deps-dev): bump @readme/oas-examples from 5.6.0 to 5.7.0 (#694) ([0cc78bc](https://github.com/readmeio/oas/commit/0cc78bc)), closes [#694](https://github.com/readmeio/oas/issues/694)
+* chore(deps-dev): bump eslint from 8.21.0 to 8.23.0 (#683) ([fa1a266](https://github.com/readmeio/oas/commit/fa1a266)), closes [#683](https://github.com/readmeio/oas/issues/683)
+* chore(deps-dev): bump eslint from 8.23.0 to 8.24.0 (#693) ([1e01334](https://github.com/readmeio/oas/commit/1e01334)), closes [#693](https://github.com/readmeio/oas/issues/693)
+* chore(deps-dev): bump ts-jest from 28.0.7 to 28.0.8 (#689) ([e129ca4](https://github.com/readmeio/oas/commit/e129ca4)), closes [#689](https://github.com/readmeio/oas/issues/689)
+* chore(deps-dev): bump typescript from 4.7.4 to 4.8.2 (#681) ([3d621b0](https://github.com/readmeio/oas/commit/3d621b0)), closes [#681](https://github.com/readmeio/oas/issues/681)
+* chore(deps-dev): bump typescript from 4.8.2 to 4.8.4 (#692) ([9eb852b](https://github.com/readmeio/oas/commit/9eb852b)), closes [#692](https://github.com/readmeio/oas/issues/692)
+* chore(deps): bump openapi-types from 12.0.0 to 12.0.2 (#688) ([61805d2](https://github.com/readmeio/oas/commit/61805d2)), closes [#688](https://github.com/readmeio/oas/issues/688)
+* chore(deps): bump swagger-inline from 6.0.0 to 6.1.0 (#687) ([15b46f0](https://github.com/readmeio/oas/commit/15b46f0)), closes [#687](https://github.com/readmeio/oas/issues/687)
+* 📝 Add commands section (#691) ([28afb82](https://github.com/readmeio/oas/commit/28afb82)), closes [#691](https://github.com/readmeio/oas/issues/691)
+
+
+
 ## <small>18.4.4 (2022-08-23)</small>
 
 * fix: bug in `getHeaders` where it wouldn't return `Authorization` if security was oauth2 (#680) ([9b49bec](https://github.com/readmeio/oas/commit/9b49bec)), closes [#680](https://github.com/readmeio/oas/issues/680)
@@ -1800,6 +1820,3 @@ Republishing 4.1.0 to 5.0.0 as `flattenSchema` is now an async method so it's a
 * Validate swagger files ([4bf6f73](https://github.com/readmeio/oas/commit/4bf6f73))
 * version 0.1.2 ([349ba96](https://github.com/readmeio/oas/commit/349ba96))
 * Weight help items ([fffc107](https://github.com/readmeio/oas/commit/fffc107))
-
-
-

package/README.md

@@ -25,6 +25,18 @@ oas init
 
 It will walk you through how to document your API with a OpenAPI 3.0 Spec.
 
+#### Commands
+
+```
+Usage: oas <command>
+
+  $ oas init                    Create a new OpenAPI definition
+  $ oas help                    Learn what you can do with oas
+  $ oas endpoint                Learn how to document an endpoint
+  $ oas generate [oas.json]     Output your OpenAPI definition (use --pretty for colors)
+  $ oas validate [oas.json]     Validate your OpenAPI definition
+```
+
 ### Swagger Inline
 
 `oas` uses [swagger-inline](https://github.com/readmeio/swagger-inline) which allows you include a little OpenAPI snippet in a comment above your code, and collects them all together into one OpenAPI file:

package/dist/index.d.ts

@@ -130,10 +130,11 @@ export default class Oas {
      *
      * @param path Path to lookup and retrieve.
      * @param method HTTP Method to retrieve on the path.
-     * @param opts Options
-     * @param opts.isWebhook If you prefer to first look for a webhook with this path and method.
      */
     operation(path: string, method: RMOAS.HttpMethods, opts?: {
+        /**
+         * If you prefer to first look for a webhook with this path and method.
+         */
         isWebhook?: boolean;
     }): Operation;
     findOperationMatches(url: string): PathMatches;
@@ -220,10 +221,11 @@ 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 Options
-     * @param opts.preserveRefAsJSONSchemaTitle Preserve component schema names within themselves as a `title`.
      */
     dereference(opts?: {
+        /**
+         * Preserve component schema names within themselves as a `title`.
+         */
         preserveRefAsJSONSchemaTitle: boolean;
     }): Promise<unknown>;
 }

package/dist/index.js

@@ -459,8 +459,6 @@ var Oas = /** @class */ (function () {
      *
      * @param path Path to lookup and retrieve.
      * @param method HTTP Method to retrieve on the path.
-     * @param opts Options
-     * @param opts.isWebhook If you prefer to first look for a webhook with this path and method.
      */
     Oas.prototype.operation = function (path, method, opts) {
         var _a, _b, _c, _d;
@@ -724,8 +722,6 @@ 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 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/get-mediatype-examples.d.ts

@@ -14,8 +14,14 @@ export declare type MediaTypeExample = {
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject}
  * @param mediaType The media type that we're looking for examples for.
  * @param mediaTypeObject The media type object that we're looking for examples for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
  */
-export default function getMediaTypeExamples(mediaType: string, mediaTypeObject: RMOAS.MediaTypeObject, opts?: {}): MediaTypeExample[];
+export default function getMediaTypeExamples(mediaType: string, mediaTypeObject: RMOAS.MediaTypeObject, opts?: {
+    /**
+     * If you wish to include data that's flagged as `readOnly`.
+     */
+    includeReadOnly?: boolean;
+    /**
+     * If you wish to include data that's flatted as `writeOnly`.
+     */
+    includeWriteOnly?: boolean;
+}): MediaTypeExample[];

package/dist/lib/get-mediatype-examples.js

@@ -14,9 +14,6 @@ var matches_mimetype_1 = __importDefault(require("./matches-mimetype"));
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject}
  * @param mediaType The media type that we're looking for examples for.
  * @param mediaTypeObject The media type object that we're looking for examples for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
  */
 function getMediaTypeExamples(mediaType, mediaTypeObject, opts) {
     if (opts === void 0) { opts = {}; }

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

@@ -1,12 +1,34 @@
 import * as RMOAS from '../rmoas.types';
 declare type PrevSchemasType = RMOAS.SchemaObject[];
 export declare type toJSONSchemaOptions = {
+    /**
+     * Whether or not to extend descriptions with a list of any present enums.
+     */
     addEnumsToDescriptions?: boolean;
+    /**
+     * Current location within the schema -- this is a JSON pointer.
+     */
     currentLocation?: string;
+    /**
+     * Object containing a global set of defaults that we should apply to schemas that match it.
+     */
     globalDefaults?: Record<string, unknown>;
+    /**
+     * Is this schema the child of a polymorphic `allOf` schema?
+     */
     isPolymorphicAllOfChild?: boolean;
+    /**
+     * Array of parent schemas to utilize when attempting to path together examples.
+     */
     prevSchemas?: PrevSchemasType;
+    /**
+     * A function that's called anytime a (circular) `$ref` is found.
+     */
     refLogger?: (ref: string) => void;
+    /**
+     * A function that's called to potentially transform any discovered schema.
+     */
+    transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
 };
 export declare function getSchemaVersionString(schema: RMOAS.SchemaObject, api: RMOAS.OASDocument): string;
 export declare function isPrimitive(val: unknown): boolean;
@@ -45,13 +67,6 @@ export declare function isPrimitive(val: unknown): boolean;
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
  * @param data OpenAPI Schema Object to convert to pure JSON Schema.
- * @param opts Options
- * @param opts.addEnumsToDescriptions Whether or not to extend descriptions with a list of any present enums.
- * @param opts.currentLocation Current location within the schema -- this is a JSON pointer.
- * @param opts.globalDefaults Object containing a global set of defaults that we should apply to schemas that match it.
- * @param opts.isPolymorphicAllOfChild Is this schema the child of a polymorphic `allOf` schema?
- * @param opts.prevSchemas Array of parent schemas to utilize when attempting to path together examples.
- * @param opts.refLogger A function that's called anytime a (circular) `$ref` is found.
  */
 export default function toJSONSchema(data: RMOAS.SchemaObject | boolean, opts?: toJSONSchemaOptions): RMOAS.SchemaObject;
 export {};

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

@@ -260,26 +260,19 @@ function searchForExampleByPointer(pointer, examples) {
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
  * @param data OpenAPI Schema Object to convert to pure JSON Schema.
- * @param opts Options
- * @param opts.addEnumsToDescriptions Whether or not to extend descriptions with a list of any present enums.
- * @param opts.currentLocation Current location within the schema -- this is a JSON pointer.
- * @param opts.globalDefaults Object containing a global set of defaults that we should apply to schemas that match it.
- * @param opts.isPolymorphicAllOfChild Is this schema the child of a polymorphic `allOf` schema?
- * @param opts.prevSchemas Array of parent schemas to utilize when attempting to path together examples.
- * @param opts.refLogger A function that's called anytime a (circular) `$ref` is found.
  */
 function toJSONSchema(data, opts) {
     if (opts === void 0) { opts = {}; }
     var schema = data === true ? {} : __assign({}, data);
     var schemaAdditionalProperties = RMOAS.isSchema(schema) ? schema.additionalProperties : null;
-    var _a = __assign({ addEnumsToDescriptions: false, currentLocation: '', globalDefaults: {}, isPolymorphicAllOfChild: false, prevSchemas: [], refLogger: function () { return true; } }, opts), addEnumsToDescriptions = _a.addEnumsToDescriptions, currentLocation = _a.currentLocation, globalDefaults = _a.globalDefaults, isPolymorphicAllOfChild = _a.isPolymorphicAllOfChild, prevSchemas = _a.prevSchemas, refLogger = _a.refLogger;
+    var _a = __assign({ addEnumsToDescriptions: false, currentLocation: '', globalDefaults: {}, isPolymorphicAllOfChild: false, prevSchemas: [], refLogger: function () { return true; }, transformer: function (s) { return s; } }, opts), addEnumsToDescriptions = _a.addEnumsToDescriptions, currentLocation = _a.currentLocation, globalDefaults = _a.globalDefaults, isPolymorphicAllOfChild = _a.isPolymorphicAllOfChild, prevSchemas = _a.prevSchemas, refLogger = _a.refLogger, transformer = _a.transformer;
     // 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);
-        return {
+        return transformer({
             $ref: schema.$ref
-        };
+        });
     }
     // If we don't have a set type, but are dealing with an `anyOf`, `oneOf`, or `allOf`
     // representation let's run through them and make sure they're good.
@@ -325,7 +318,8 @@ function toJSONSchema(data, opts) {
                         globalDefaults: globalDefaults,
                         isPolymorphicAllOfChild: false,
                         prevSchemas: prevSchemas,
-                        refLogger: refLogger
+                        refLogger: refLogger,
+                        transformer: transformer
                     };
                     // When `properties` or `items` are present alongside a polymorphic schema instead of
                     // letting whatever JSON Schema interpreter is handling these constructed schemas we can
@@ -461,7 +455,8 @@ function toJSONSchema(data, opts) {
                         currentLocation: "".concat(currentLocation, "/0"),
                         globalDefaults: globalDefaults,
                         prevSchemas: prevSchemas,
-                        refLogger: refLogger
+                        refLogger: refLogger,
+                        transformer: transformer
                     });
                 }
             }
@@ -482,7 +477,7 @@ function toJSONSchema(data, opts) {
         }
         else if (schema.type === 'object') {
             if ('properties' in schema) {
-                Object.keys(schema.properties).map(function (prop) {
+                Object.keys(schema.properties).forEach(function (prop) {
                     if (Array.isArray(schema.properties[prop]) ||
                         (typeof schema.properties[prop] === 'object' && schema.properties[prop] !== null)) {
                         schema.properties[prop] = toJSONSchema(schema.properties[prop], {
@@ -490,10 +485,10 @@ function toJSONSchema(data, opts) {
                             currentLocation: "".concat(currentLocation, "/").concat(encodePointer(prop)),
                             globalDefaults: globalDefaults,
                             prevSchemas: prevSchemas,
-                            refLogger: refLogger
+                            refLogger: refLogger,
+                            transformer: transformer
                         });
                     }
-                    return true;
                 });
             }
             if (typeof schemaAdditionalProperties === 'object' && schemaAdditionalProperties !== null) {
@@ -512,7 +507,8 @@ function toJSONSchema(data, opts) {
                         currentLocation: currentLocation,
                         globalDefaults: globalDefaults,
                         prevSchemas: prevSchemas,
-                        refLogger: refLogger
+                        refLogger: refLogger,
+                        transformer: transformer
                     });
                 }
             }
@@ -612,6 +608,6 @@ function toJSONSchema(data, opts) {
         // typing won't work
         delete schema[UNSUPPORTED_SCHEMA_PROPS[i]];
     }
-    return schema;
+    return transformer(schema);
 }
 exports["default"] = toJSONSchema;

package/dist/lib/reducer.d.ts

@@ -19,6 +19,5 @@ export declare type ReducerOptions = {
  * { 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

@@ -53,7 +53,6 @@ function accumulateUsedRefs(schema, $refs, $ref) {
  * { 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 = {}; }

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

@@ -15,8 +15,9 @@ export declare type SchemaWrapper = {
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject}
  */
 export declare const types: Record<keyof OASDocument, string>;
-export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, opts?: {
+export default function getParametersAsJSONSchema(operation: Operation, api: OASDocument, opts?: {
     globalDefaults?: Record<string, unknown>;
     mergeIntoBodyAndMetadata?: boolean;
     retainDeprecatedProperties?: boolean;
+    transformer?: (schema: SchemaObject) => SchemaObject;
 }): SchemaWrapper[];

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

@@ -58,7 +58,7 @@ exports.types = {
     header: 'Headers',
     metadata: 'Metadata'
 };
-function getParametersAsJsonSchema(operation, api, opts) {
+function getParametersAsJSONSchema(operation, api, opts) {
     var _a;
     var hasCircularRefs = false;
     function refLogger() {
@@ -92,7 +92,8 @@ function getParametersAsJsonSchema(operation, api, opts) {
         var deprecatedSchema = (0, openapi_to_json_schema_1["default"])(deprecatedBody, {
             globalDefaults: opts.globalDefaults,
             prevSchemas: [],
-            refLogger: refLogger
+            refLogger: refLogger,
+            transformer: opts.transformer
         });
         // Check if the schema wasn't created or there's no deprecated properties
         if (Object.keys(deprecatedSchema).length === 0 || Object.keys(deprecatedSchema.properties).length === 0) {
@@ -138,7 +139,12 @@ function getParametersAsJsonSchema(operation, api, opts) {
         // We're cloning the request schema because we've had issues with request schemas that were
         // dereferenced being processed multiple times because their component is also processed.
         var requestSchema = (0, clone_object_1["default"])(mediaTypeObject.schema);
-        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, { globalDefaults: opts.globalDefaults, prevSchemas: prevSchemas, refLogger: refLogger });
+        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, {
+            globalDefaults: opts.globalDefaults,
+            prevSchemas: prevSchemas,
+            refLogger: refLogger,
+            transformer: opts.transformer
+        });
         // If this schema is **still** empty, don't bother returning it.
         if (!Object.keys(cleanedSchema).length) {
             return null;
@@ -169,7 +175,8 @@ function getParametersAsJsonSchema(operation, api, opts) {
                     var componentSchema = (0, clone_object_1["default"])(api.components[componentType][schemaName]);
                     components[componentType][schemaName] = (0, openapi_to_json_schema_1["default"])(componentSchema, {
                         globalDefaults: opts.globalDefaults,
-                        refLogger: refLogger
+                        refLogger: refLogger,
+                        transformer: opts.transformer
                     });
                 });
             }
@@ -206,7 +213,8 @@ function getParametersAsJsonSchema(operation, api, opts) {
                     schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
                         currentLocation: "/".concat(current.name),
                         globalDefaults: opts.globalDefaults,
-                        refLogger: refLogger
+                        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
@@ -251,7 +259,8 @@ function getParametersAsJsonSchema(operation, api, opts) {
                             schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
                                 currentLocation: "/".concat(current.name),
                                 globalDefaults: opts.globalDefaults,
-                                refLogger: refLogger
+                                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
@@ -343,4 +352,4 @@ function getParametersAsJsonSchema(operation, api, opts) {
         return typeKeys.indexOf(a.type) - typeKeys.indexOf(b.type);
     });
 }
-exports["default"] = getParametersAsJsonSchema;
+exports["default"] = getParametersAsJSONSchema;

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

@@ -1,7 +1,7 @@
 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.
+ * Extract all the response schemas, matching the format of `get-parameters-as-json-schema`.
  *
  * Note: This expects a dereferenced schema.
  *
@@ -9,7 +9,14 @@ import type { OASDocument, SchemaObject } from 'rmoas.types';
  * @param api The OpenAPI definition that this operation originates.
  * @param statusCode The response status code to generate a schema for.
  */
-export default function getResponseAsJsonSchema(operation: Operation, api: OASDocument, statusCode: string | number): {
+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.
+     */
+    transformer?: (schema: SchemaObject) => SchemaObject;
+}): {
     type: string | string[];
     schema: SchemaObject;
     label: string;

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

@@ -50,7 +50,7 @@ var isJSON = matches_mimetype_1["default"].json;
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.3.md#headerObject}
  * @param response Response object to build a JSON Schema object for its headers for.
  */
-function buildHeadersSchema(response) {
+function buildHeadersSchema(response, opts) {
     var headers = response.headers;
     var headersSchema = {
         type: 'object',
@@ -62,7 +62,10 @@ function buildHeadersSchema(response) {
             // TODO: Response headers are essentially parameters in OAS
             //    This means they can have content instead of schema.
             //    We should probably support that in the future
-            headersSchema.properties[key] = (0, openapi_to_json_schema_1["default"])(header.schema, { addEnumsToDescriptions: true });
+            headersSchema.properties[key] = (0, openapi_to_json_schema_1["default"])(header.schema, {
+                addEnumsToDescriptions: true,
+                transformer: opts.transformer
+            });
             if (header.description) {
                 headersSchema.properties[key].description = header.description;
             }
@@ -79,7 +82,7 @@ function buildHeadersSchema(response) {
     return headersWrapper;
 }
 /**
- * Extract all the response schemas, matching the format of get-parameters-as-json-schema.
+ * Extract all the response schemas, matching the format of `get-parameters-as-json-schema`.
  *
  * Note: This expects a dereferenced schema.
  *
@@ -87,7 +90,7 @@ function buildHeadersSchema(response) {
  * @param api The OpenAPI definition that this operation originates.
  * @param statusCode The response status code to generate a schema for.
  */
-function getResponseAsJsonSchema(operation, api, statusCode) {
+function getResponseAsJSONSchema(operation, api, statusCode, opts) {
     var response = operation.getResponseByStatusCode(statusCode);
     var jsonSchema = [];
     if (!response) {
@@ -112,13 +115,21 @@ function getResponseAsJsonSchema(operation, api, statusCode) {
         // eslint-disable-next-line no-plusplus
         for (var i = 0; i < contentTypes.length; i++) {
             if (isJSON(contentTypes[i])) {
-                return (0, openapi_to_json_schema_1["default"])((0, clone_object_1["default"])(content[contentTypes[i]].schema), { addEnumsToDescriptions: true, refLogger: refLogger });
+                return (0, openapi_to_json_schema_1["default"])((0, clone_object_1["default"])(content[contentTypes[i]].schema), {
+                    addEnumsToDescriptions: true,
+                    refLogger: refLogger,
+                    transformer: opts.transformer
+                });
             }
         }
         // We always want to prefer the JSON-compatible content types over everything else but if we
         // haven't found one we should default to the first available.
         var contentType = contentTypes.shift();
-        return (0, openapi_to_json_schema_1["default"])((0, clone_object_1["default"])(content[contentType].schema), { addEnumsToDescriptions: true, refLogger: refLogger });
+        return (0, openapi_to_json_schema_1["default"])((0, clone_object_1["default"])(content[contentType].schema), {
+            addEnumsToDescriptions: true,
+            refLogger: refLogger,
+            transformer: opts.transformer
+        });
     }
     var foundSchema = getPreferredSchema(response.content);
     if (foundSchema) {
@@ -148,8 +159,8 @@ function getResponseAsJsonSchema(operation, api, statusCode) {
     }
     // 3.0.3 and earlier headers. TODO: New format for 3.1.0
     if (response.headers) {
-        jsonSchema.push(buildHeadersSchema(response));
+        jsonSchema.push(buildHeadersSchema(response, opts));
     }
     return jsonSchema.length ? jsonSchema : null;
 }
-exports["default"] = getResponseAsJsonSchema;
+exports["default"] = getResponseAsJSONSchema;

package/dist/operation.d.ts

@@ -89,10 +89,11 @@ 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 Options
-     * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
     getOperationId(opts?: {
+        /**
+         * Generate a JS method-friendly operation ID when one isn't present.
+         */
         camelCase: boolean;
     }): string;
     /**
@@ -124,25 +125,42 @@ 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 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
-     *    `header`).
-     * @param opts.retainDeprecatedProperties If you wish to **not** split out deprecated properties
-     *    into a separate `deprecatedProps` object.
-     */
-    getParametersAsJsonSchema(opts?: {
+     */
+    getParametersAsJSONSchema(opts?: {
+        /**
+         * Contains an object of user defined schema defaults.
+         */
         globalDefaults?: Record<string, unknown>;
+        /**
+         * If you want the output to be two objects: body (contains `body` and `formData` JSON
+         * Schema) and metadata (contains `path`, `query`, `cookie`, and `header`).
+         */
         mergeIntoBodyAndMetadata?: boolean;
+        /**
+         * If you wish to **not** split out deprecated properties into a separate `deprecatedProps`
+         * object.
+         */
         retainDeprecatedProperties?: 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;
     }): import("./operation/get-parameters-as-json-schema").SchemaWrapper[];
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
      * @param statusCode Status code to pull a JSON Schema response for.
      */
-    getResponseAsJsonSchema(statusCode: string | number): {
+    getResponseAsJSONSchema(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.
+         */
+        transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
+    }): {
         type: string | string[];
         schema: RMOAS.SchemaObject;
         label: string;

package/dist/operation.js

@@ -304,24 +304,27 @@ 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 Options
-     * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
     Operation.prototype.getOperationId = function (opts) {
+        function sanitize(id) {
+            return id
+                .replace(/[^a-zA-Z0-9_]/g, '-') // Remove weird characters
+                .replace(/^-|-$/g, '') // Don't start or end with -
+                .replace(/--+/g, '-'); // Remove double --'s
+        }
         var operationId;
         if (this.hasOperationId()) {
             operationId = this.schema.operationId;
         }
         else {
-            operationId = this.path
-                .replace(/[^a-zA-Z0-9]/g, '-') // Remove weird characters
-                .replace(/^-|-$/g, '') // Don't start or end with -
-                .replace(/--+/g, '-') // Remove double --'s
-                .toLowerCase();
+            operationId = sanitize(this.path).toLowerCase();
         }
         var method = this.method.toLowerCase();
         if (opts === null || opts === void 0 ? void 0 : opts.camelCase) {
             operationId = operationId.replace(/[^a-zA-Z0-9_]+(.)/g, function (_, chr) { return chr.toUpperCase(); });
+            if (this.hasOperationId()) {
+                operationId = sanitize(operationId);
+            }
             // If the generated `operationId` already starts with the method (eg. `getPets`) we don't want
             // to double it up into `getGetPets`.
             if (operationId.startsWith(method)) {
@@ -408,16 +411,12 @@ 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 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
-     *    `header`).
-     * @param opts.retainDeprecatedProperties If you wish to **not** split out deprecated properties
-     *    into a separate `deprecatedProps` object.
      */
-    Operation.prototype.getParametersAsJsonSchema = function (opts) {
+    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);
     };
     /**
@@ -425,8 +424,11 @@ var Operation = /** @class */ (function () {
      *
      * @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);
+    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);
     };
     /**
      * Get an array of all valid response status codes for this operation.
@@ -483,7 +485,7 @@ var Operation = /** @class */ (function () {
         // final point where we don't have a required request body, but the underlying Media Type Object
         // schema says that it has required properties then we should ultimately recognize that this
         // request body is required -- even as the request body description says otherwise.
-        return !!this.getParametersAsJsonSchema()
+        return !!this.getParametersAsJSONSchema()
             .filter(function (js) { return ['body', 'formData'].includes(js.type); })
             .find(function (js) { return js.schema && Array.isArray(js.schema.required) && js.schema.required.length; });
     };

package/dist/samples/index.d.ts

@@ -12,13 +12,15 @@ import memoize from 'memoizee';
  * the schema.
  *
  * @param schema JSON Schema to generate a sample for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
- * @returns A generated piece of data based off the JSON Schema that was supplied.
  */
 declare function sampleFromSchema(schema: RMOAS.SchemaObject, opts?: {
+    /**
+     * If you wish to include data that's flagged as `readOnly`.
+     */
     includeReadOnly?: boolean;
+    /**
+     * If you wish to include data that's flatted as `writeOnly`.
+     */
     includeWriteOnly?: boolean;
 }): string | number | boolean | null | unknown[] | Record<string, unknown> | undefined;
 declare const _default: typeof sampleFromSchema & memoize.Memoized<typeof sampleFromSchema>;

package/dist/samples/index.js

@@ -42,10 +42,6 @@ var primitive = function (schema) {
  * the schema.
  *
  * @param schema JSON Schema to generate a sample for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
- * @returns A generated piece of data based off the JSON Schema that was supplied.
  */
 function sampleFromSchema(schema, opts) {
     if (opts === void 0) { opts = {}; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "18.4.4",
+  "version": "19.0.0",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -75,6 +75,7 @@
     "@types/json-schema-merge-allof": "^0.6.1",
     "@types/jsonpath": "^0.2.0",
     "@types/memoizee": "^0.4.6",
+    "@types/node": "^18.8.2",
     "eslint": "^8.20.0",
     "husky": "^8.0.1",
     "jest": "^28.1.3",

package/src/index.ts

@@ -466,10 +466,17 @@ export default class Oas {
    *
    * @param path Path to lookup and retrieve.
    * @param method HTTP Method to retrieve on the path.
-   * @param opts Options
-   * @param opts.isWebhook If you prefer to first look for a webhook with this path and method.
    */
-  operation(path: string, method: RMOAS.HttpMethods, opts: { isWebhook?: boolean } = {}) {
+  operation(
+    path: string,
+    method: RMOAS.HttpMethods,
+    opts: {
+      /**
+       * If you prefer to first look for a webhook with this path and method.
+       */
+      isWebhook?: boolean;
+    } = {}
+  ) {
     // If we're unable to locate an operation for this path+method combination within the API
     // definition, we should still set an empty schema on the operation in the `Operation` class
     // because if we don't trying to use any of the accessors on that class are going to fail as
@@ -758,10 +765,15 @@ 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 Options
-   * @param opts.preserveRefAsJSONSchemaTitle Preserve component schema names within themselves as a `title`.
    */
-  async dereference(opts = { preserveRefAsJSONSchemaTitle: false }) {
+  async dereference(
+    opts: {
+      /**
+       * Preserve component schema names within themselves as a `title`.
+       */
+      preserveRefAsJSONSchemaTitle: boolean;
+    } = { preserveRefAsJSONSchemaTitle: false }
+  ) {
     if (this.dereferencing.complete) {
       return new Promise(resolve => {
         resolve(true);

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

@@ -20,11 +20,22 @@ export type MediaTypeExample = {
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject}
  * @param mediaType The media type that we're looking for examples for.
  * @param mediaTypeObject The media type object that we're looking for examples for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
  */
-export default function getMediaTypeExamples(mediaType: string, mediaTypeObject: RMOAS.MediaTypeObject, opts = {}) {
+export default function getMediaTypeExamples(
+  mediaType: string,
+  mediaTypeObject: RMOAS.MediaTypeObject,
+  opts: {
+    /**
+     * If you wish to include data that's flagged as `readOnly`.
+     */
+    includeReadOnly?: boolean;
+
+    /**
+     * If you wish to include data that's flatted as `writeOnly`.
+     */
+    includeWriteOnly?: boolean;
+  } = {}
+) {
   if (mediaTypeObject.example) {
     return [
       {

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

@@ -28,12 +28,40 @@ const UNSUPPORTED_SCHEMA_PROPS: ('nullable' | 'xml' | 'externalDocs' | 'example'
 type PrevSchemasType = RMOAS.SchemaObject[];
 
 export type toJSONSchemaOptions = {
+  /**
+   * Whether or not to extend descriptions with a list of any present enums.
+   */
   addEnumsToDescriptions?: boolean;
+
+  /**
+   * Current location within the schema -- this is a JSON pointer.
+   */
   currentLocation?: string;
+
+  /**
+   * Object containing a global set of defaults that we should apply to schemas that match it.
+   */
   globalDefaults?: Record<string, unknown>;
+
+  /**
+   * Is this schema the child of a polymorphic `allOf` schema?
+   */
   isPolymorphicAllOfChild?: boolean;
+
+  /**
+   * Array of parent schemas to utilize when attempting to path together examples.
+   */
   prevSchemas?: PrevSchemasType;
+
+  /**
+   * A function that's called anytime a (circular) `$ref` is found.
+   */
   refLogger?: (ref: string) => void;
+
+  /**
+   * A function that's called to potentially transform any discovered schema.
+   */
+  transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
 };
 
 /**
@@ -237,13 +265,6 @@ function searchForExampleByPointer(pointer: string, examples: PrevSchemasType =
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
  * @param data OpenAPI Schema Object to convert to pure JSON Schema.
- * @param opts Options
- * @param opts.addEnumsToDescriptions Whether or not to extend descriptions with a list of any present enums.
- * @param opts.currentLocation Current location within the schema -- this is a JSON pointer.
- * @param opts.globalDefaults Object containing a global set of defaults that we should apply to schemas that match it.
- * @param opts.isPolymorphicAllOfChild Is this schema the child of a polymorphic `allOf` schema?
- * @param opts.prevSchemas Array of parent schemas to utilize when attempting to path together examples.
- * @param opts.refLogger A function that's called anytime a (circular) `$ref` is found.
  */
 export default function toJSONSchema(
   data: RMOAS.SchemaObject | boolean,
@@ -252,13 +273,22 @@ export default function toJSONSchema(
   let schema = data === true ? {} : { ...data };
   const schemaAdditionalProperties = RMOAS.isSchema(schema) ? schema.additionalProperties : null;
 
-  const { addEnumsToDescriptions, currentLocation, globalDefaults, isPolymorphicAllOfChild, prevSchemas, refLogger } = {
+  const {
+    addEnumsToDescriptions,
+    currentLocation,
+    globalDefaults,
+    isPolymorphicAllOfChild,
+    prevSchemas,
+    refLogger,
+    transformer,
+  } = {
     addEnumsToDescriptions: false,
     currentLocation: '',
     globalDefaults: {},
     isPolymorphicAllOfChild: false,
     prevSchemas: [] as PrevSchemasType,
     refLogger: () => true,
+    transformer: (s: RMOAS.SchemaObject) => s,
     ...opts,
   };
 
@@ -267,9 +297,9 @@ export default function toJSONSchema(
   if (RMOAS.isRef(schema)) {
     refLogger(schema.$ref);
 
-    return {
+    return transformer({
       $ref: schema.$ref,
-    };
+    });
   }
 
   // If we don't have a set type, but are dealing with an `anyOf`, `oneOf`, or `allOf`
@@ -319,6 +349,7 @@ export default function toJSONSchema(
             isPolymorphicAllOfChild: false,
             prevSchemas,
             refLogger,
+            transformer,
           };
 
           // When `properties` or `items` are present alongside a polymorphic schema instead of
@@ -458,6 +489,7 @@ export default function toJSONSchema(
             globalDefaults,
             prevSchemas,
             refLogger,
+            transformer,
           });
         }
       } else if ('properties' in schema || 'additionalProperties' in schema) {
@@ -475,7 +507,7 @@ export default function toJSONSchema(
       }
     } else if (schema.type === 'object') {
       if ('properties' in schema) {
-        Object.keys(schema.properties).map(prop => {
+        Object.keys(schema.properties).forEach(prop => {
           if (
             Array.isArray(schema.properties[prop]) ||
             (typeof schema.properties[prop] === 'object' && schema.properties[prop] !== null)
@@ -486,10 +518,9 @@ export default function toJSONSchema(
               globalDefaults,
               prevSchemas,
               refLogger,
+              transformer,
             });
           }
-
-          return true;
         });
       }
 
@@ -511,6 +542,7 @@ export default function toJSONSchema(
             globalDefaults,
             prevSchemas,
             refLogger,
+            transformer,
           });
         }
       }
@@ -622,5 +654,5 @@ export default function toJSONSchema(
     delete (schema as Record<string, unknown>)[UNSUPPORTED_SCHEMA_PROPS[i]];
   }
 
-  return schema;
+  return transformer(schema);
 }

package/src/lib/reducer.ts

@@ -62,7 +62,6 @@ function accumulateUsedRefs(schema: Record<string, unknown>, $refs: Set<string>,
  * { 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 : [];

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

@@ -33,13 +33,14 @@ export const types: Record<keyof OASDocument, string> = {
   metadata: 'Metadata', // This a special type reserved for https://npm.im/api
 };
 
-export default function getParametersAsJsonSchema(
+export default function getParametersAsJSONSchema(
   operation: Operation,
   api: OASDocument,
   opts?: {
     globalDefaults?: Record<string, unknown>;
     mergeIntoBodyAndMetadata?: boolean;
     retainDeprecatedProperties?: boolean;
+    transformer?: (schema: SchemaObject) => SchemaObject;
   }
 ) {
   let hasCircularRefs = false;
@@ -82,6 +83,7 @@ export default function getParametersAsJsonSchema(
       globalDefaults: opts.globalDefaults,
       prevSchemas: [],
       refLogger,
+      transformer: opts.transformer,
     });
 
     // Check if the schema wasn't created or there's no deprecated properties
@@ -136,7 +138,12 @@ export default function getParametersAsJsonSchema(
     // We're cloning the request schema because we've had issues with request schemas that were
     // dereferenced being processed multiple times because their component is also processed.
     const requestSchema = cloneObject(mediaTypeObject.schema);
-    const cleanedSchema = toJSONSchema(requestSchema, { globalDefaults: opts.globalDefaults, prevSchemas, refLogger });
+    const cleanedSchema = toJSONSchema(requestSchema, {
+      globalDefaults: opts.globalDefaults,
+      prevSchemas,
+      refLogger,
+      transformer: opts.transformer,
+    });
 
     // If this schema is **still** empty, don't bother returning it.
     if (!Object.keys(cleanedSchema).length) {
@@ -177,6 +184,7 @@ export default function getParametersAsJsonSchema(
           components[componentType][schemaName] = toJSONSchema(componentSchema as SchemaObject, {
             globalDefaults: opts.globalDefaults,
             refLogger,
+            transformer: opts.transformer,
           });
         });
       }
@@ -221,6 +229,7 @@ export default function getParametersAsJsonSchema(
                 currentLocation: `/${current.name}`,
                 globalDefaults: opts.globalDefaults,
                 refLogger,
+                transformer: opts.transformer,
               }),
 
               // Note: this applies a $schema version to each field in the larger schema object.
@@ -268,6 +277,7 @@ export default function getParametersAsJsonSchema(
                     currentLocation: `/${current.name}`,
                     globalDefaults: opts.globalDefaults,
                     refLogger,
+                    transformer: opts.transformer,
                   }),
 
                   // Note: this applies a $schema version to each field in the larger schema object.

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

@@ -23,7 +23,17 @@ const isJSON = matches.json;
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.3.md#headerObject}
  * @param response Response object to build a JSON Schema object for its headers for.
  */
-function buildHeadersSchema(response: ResponseObject) {
+function buildHeadersSchema(
+  response: ResponseObject,
+  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.
+     */
+    transformer?: (schema: SchemaObject) => SchemaObject;
+  }
+) {
   const headers = response.headers;
 
   const headersSchema: SchemaObject = {
@@ -38,7 +48,10 @@ function buildHeadersSchema(response: ResponseObject) {
       // TODO: Response headers are essentially parameters in OAS
       //    This means they can have content instead of schema.
       //    We should probably support that in the future
-      headersSchema.properties[key] = toJSONSchema(header.schema, { addEnumsToDescriptions: true });
+      headersSchema.properties[key] = toJSONSchema(header.schema, {
+        addEnumsToDescriptions: true,
+        transformer: opts.transformer,
+      });
 
       if (header.description) {
         (headersSchema.properties[key] as HeaderObject).description = header.description;
@@ -65,7 +78,7 @@ function buildHeadersSchema(response: ResponseObject) {
 }
 
 /**
- * Extract all the response schemas, matching the format of get-parameters-as-json-schema.
+ * Extract all the response schemas, matching the format of `get-parameters-as-json-schema`.
  *
  * Note: This expects a dereferenced schema.
  *
@@ -73,7 +86,19 @@ function buildHeadersSchema(response: ResponseObject) {
  * @param api The OpenAPI definition that this operation originates.
  * @param statusCode The response status code to generate a schema for.
  */
-export default function getResponseAsJsonSchema(operation: Operation, api: OASDocument, statusCode: string | number) {
+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.
+     */
+    transformer?: (schema: SchemaObject) => SchemaObject;
+  }
+) {
   const response = operation.getResponseByStatusCode(statusCode);
   const jsonSchema = [];
 
@@ -104,14 +129,22 @@ export default function getResponseAsJsonSchema(operation: Operation, api: OASDo
     // eslint-disable-next-line no-plusplus
     for (let i = 0; i < contentTypes.length; i++) {
       if (isJSON(contentTypes[i])) {
-        return toJSONSchema(cloneObject(content[contentTypes[i]].schema), { addEnumsToDescriptions: true, refLogger });
+        return toJSONSchema(cloneObject(content[contentTypes[i]].schema), {
+          addEnumsToDescriptions: true,
+          refLogger,
+          transformer: opts.transformer,
+        });
       }
     }
 
     // We always want to prefer the JSON-compatible content types over everything else but if we
     // haven't found one we should default to the first available.
     const contentType = contentTypes.shift();
-    return toJSONSchema(cloneObject(content[contentType].schema), { addEnumsToDescriptions: true, refLogger });
+    return toJSONSchema(cloneObject(content[contentType].schema), {
+      addEnumsToDescriptions: true,
+      refLogger,
+      transformer: opts.transformer,
+    });
   }
 
   const foundSchema = getPreferredSchema((response as ResponseObject).content);
@@ -154,7 +187,7 @@ export default function getResponseAsJsonSchema(operation: Operation, api: OASDo
 
   // 3.0.3 and earlier headers. TODO: New format for 3.1.0
   if ((response as ResponseObject).headers) {
-    jsonSchema.push(buildHeadersSchema(response as ResponseObject));
+    jsonSchema.push(buildHeadersSchema(response as ResponseObject, opts));
   }
 
   return jsonSchema.length ? jsonSchema : null;

package/src/operation.ts

@@ -7,9 +7,9 @@ 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 getParametersAsJSONSchema from './operation/get-parameters-as-json-schema';
 import getRequestBodyExamples from './operation/get-requestbody-examples';
-import getResponseAsJsonSchema from './operation/get-response-as-json-schema';
+import getResponseAsJSONSchema from './operation/get-response-as-json-schema';
 import getResponseExamples from './operation/get-response-examples';
 import * as RMOAS from './rmoas.types';
 import { supportedMethods } from './utils';
@@ -332,24 +332,33 @@ 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 Options
-   * @param opts.camelCase Generate a JS method-friendly operation ID when one isn't present.
    */
-  getOperationId(opts?: { camelCase: boolean }): string {
+  getOperationId(opts?: {
+    /**
+     * Generate a JS method-friendly operation ID when one isn't present.
+     */
+    camelCase: boolean;
+  }): string {
+    function sanitize(id: string) {
+      return id
+        .replace(/[^a-zA-Z0-9_]/g, '-') // Remove weird characters
+        .replace(/^-|-$/g, '') // Don't start or end with -
+        .replace(/--+/g, '-'); // Remove double --'s
+    }
+
     let operationId;
     if (this.hasOperationId()) {
       operationId = this.schema.operationId;
     } else {
-      operationId = this.path
-        .replace(/[^a-zA-Z0-9]/g, '-') // Remove weird characters
-        .replace(/^-|-$/g, '') // Don't start or end with -
-        .replace(/--+/g, '-') // Remove double --'s
-        .toLowerCase();
+      operationId = sanitize(this.path).toLowerCase();
     }
 
     const method = this.method.toLowerCase();
     if (opts?.camelCase) {
       operationId = operationId.replace(/[^a-zA-Z0-9_]+(.)/g, (_, chr) => chr.toUpperCase());
+      if (this.hasOperationId()) {
+        operationId = sanitize(operationId);
+      }
 
       // If the generated `operationId` already starts with the method (eg. `getPets`) we don't want
       // to double it up into `getGetPets`.
@@ -448,22 +457,39 @@ 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 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
-   *    `header`).
-   * @param opts.retainDeprecatedProperties If you wish to **not** split out deprecated properties
-   *    into a separate `deprecatedProps` object.
-   */
-  getParametersAsJsonSchema(
+   */
+  getParametersAsJSONSchema(
     opts: {
+      /**
+       * Contains an object of user defined schema defaults.
+       */
       globalDefaults?: Record<string, unknown>;
+
+      /**
+       * If you want the output to be two objects: body (contains `body` and `formData` JSON
+       * Schema) and metadata (contains `path`, `query`, `cookie`, and `header`).
+       */
       mergeIntoBodyAndMetadata?: boolean;
+
+      /**
+       * If you wish to **not** split out deprecated properties into a separate `deprecatedProps`
+       * object.
+       */
       retainDeprecatedProperties?: 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;
     } = {}
   ) {
-    return getParametersAsJsonSchema(this, this.api, opts);
+    if (!opts.transformer) {
+      opts.transformer = (s: RMOAS.SchemaObject) => s;
+    }
+
+    return getParametersAsJSONSchema(this, this.api, opts);
   }
 
   /**
@@ -471,8 +497,20 @@ export default class Operation {
    *
    * @param statusCode Status code to pull a JSON Schema response for.
    */
-  getResponseAsJsonSchema(statusCode: string | number) {
-    return getResponseAsJsonSchema(this, this.api, statusCode);
+  getResponseAsJSONSchema(
+    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.
+       */
+      transformer?: (schema: RMOAS.SchemaObject) => RMOAS.SchemaObject;
+    } = {
+      transformer: (s: RMOAS.SchemaObject) => s,
+    }
+  ) {
+    return getResponseAsJSONSchema(this, this.api, statusCode, opts);
   }
 
   /**
@@ -538,7 +576,7 @@ export default class Operation {
     // final point where we don't have a required request body, but the underlying Media Type Object
     // schema says that it has required properties then we should ultimately recognize that this
     // request body is required -- even as the request body description says otherwise.
-    return !!this.getParametersAsJsonSchema()
+    return !!this.getParametersAsJSONSchema()
       .filter(js => ['body', 'formData'].includes(js.type))
       .find(js => js.schema && Array.isArray(js.schema.required) && js.schema.required.length);
   }

package/src/samples/index.ts

@@ -51,14 +51,20 @@ const primitive = (schema: RMOAS.SchemaObject) => {
  * the schema.
  *
  * @param schema JSON Schema to generate a sample for.
- * @param opts Options
- * @param opts.includeReadOnly If you wish to include data that's flagged as `readOnly`.
- * @param opts.includeWriteOnly If you wish to include data that's flatted as `writeOnly`.
- * @returns A generated piece of data based off the JSON Schema that was supplied.
  */
 function sampleFromSchema(
   schema: RMOAS.SchemaObject,
-  opts: { includeReadOnly?: boolean; includeWriteOnly?: boolean } = {}
+  opts: {
+    /**
+     * If you wish to include data that's flagged as `readOnly`.
+     */
+    includeReadOnly?: boolean;
+
+    /**
+     * If you wish to include data that's flatted as `writeOnly`.
+     */
+    includeWriteOnly?: boolean;
+  } = {}
 ): string | number | boolean | null | unknown[] | Record<string, unknown> | undefined {
   const objectifySchema = objectify(schema);
   let { type } = objectifySchema;