oas 17.8.0 → 18.0.1

package/@types/lib/find-schema-definition.d.ts

@@ -1,6 +1,7 @@
 /**
  * Lookup a reference pointer within an OpenAPI definition and return the schema that it resolves to.
  *
+ * @deprecated
  * @param $ref Reference to look up a schema for.
  * @param definitions OpenAPI definition to look for the `$ref` pointer in.
  */

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

@@ -15,9 +15,8 @@ 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 RMOAS.OASDocument, string>;
-/**
- * @param operation
- * @param api
- * @param globalDefaults
- */
-export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, globalDefaults?: {}): SchemaWrapper[];
+export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, opts?: {
+    globalDefaults?: Record<string, unknown>;
+    mergeIntoBodyAndMetadata?: boolean;
+    retainDeprecatedProperties?: boolean;
+}): SchemaWrapper[];

package/@types/operation.d.ts

@@ -84,11 +84,15 @@ export default class Operation {
      */
     hasOperationId(): boolean;
     /**
-     * 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.
+     * 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.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
-    getOperationId(): string;
+    getOperationId(opts?: {
+        camelCase: boolean;
+    }): string;
     /**
      * Return an array of all tags, and their metadata, that exist on this operation.
      *
@@ -109,13 +113,28 @@ export default class Operation {
      *
      */
     getParameters(): RMOAS.ParameterObject[];
+    /**
+     * Determine if this operation has any required parameters.
+     *
+     */
+    hasRequiredParameters(): boolean;
     /**
      * Convert the operation into an array of JSON Schema schemas for each available type of parameter available on the
      * operation.
      *
-     * @param globalDefaults Contains an object of user defined schema defaults.
-     */
-    getParametersAsJsonSchema(globalDefaults?: Record<string, unknown>): import("./operation/get-parameters-as-json-schema").SchemaWrapper[];
+     * @param opts
+     * @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?: {
+        globalDefaults?: Record<string, unknown>;
+        mergeIntoBodyAndMetadata?: boolean;
+        retainDeprecatedProperties?: boolean;
+    }): import("./operation/get-parameters-as-json-schema").SchemaWrapper[];
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
@@ -144,6 +163,11 @@ export default class Operation {
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
      */
     getRequestBodyMediaTypes(): string[];
+    /**
+     * Determine if this operation has a required request body.
+     *
+     */
+    hasRequiredRequestBody(): boolean;
     /**
      * Retrieve a specific request body content schema off this operation.
      *

package/@types/rmoas.types.d.ts

@@ -111,6 +111,7 @@ export declare type HeaderObject = OpenAPIV3.HeaderObject | OpenAPIV3_1.HeaderOb
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
  */
 export declare type SchemaObject = (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject | JSONSchema) & {
+    $schema?: string;
     deprecated?: boolean;
     readOnly?: boolean;
     writeOnly?: boolean;

package/@types/utils.d.ts

@@ -1,9 +1,7 @@
 import findSchemaDefinition from './lib/find-schema-definition';
-import getSchema from './lib/get-schema';
 declare const supportedMethods: Set<string>;
 declare const _default: {
     findSchemaDefinition: typeof findSchemaDefinition;
-    getSchema: typeof getSchema;
     jsonSchemaTypes: Record<string, string>;
     matchesMimeType: {
         formUrlEncoded: (mimeType: string) => boolean;

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## <small>18.0.1 (2022-03-10)</small>
+
+* fix: don't create an empty metadata allOf is there's no metadata (#619) ([28a7752](https://github.com/readmeio/oas/commit/28a7752)), closes [#619](https://github.com/readmeio/oas/issues/619)
+
+
+
+## 18.0.0 (2022-03-08)
+
+> **BREAKING CHANGE**
+>
+> The method signature for `Operation.getParametersAsJsonSchema()` has been slightly altered and the `getSchema` export has been removed. If you don't use any of the tooling library offered by this library then you don't need to do anything!
+
+* chore(deps-dev): bumping dev deps ([08833bb](https://github.com/readmeio/oas/commit/08833bb))
+* docs: integrating alex into our documentation process (#618) ([4c08f13](https://github.com/readmeio/oas/commit/4c08f13)), closes [#618](https://github.com/readmeio/oas/issues/618)
+* feat: adding new options to `getParametersAsJsonSchema` (#617) ([7b17b9f](https://github.com/readmeio/oas/commit/7b17b9f)), closes [#617](https://github.com/readmeio/oas/issues/617)
+* feat: removing getSchema, deprecating findSchemaDefinition (#600) ([161611f](https://github.com/readmeio/oas/commit/161611f)), closes [#600](https://github.com/readmeio/oas/issues/600)
+
+
+
+## <small>17.8.1 (2022-03-04)</small>
+
+* fix: typo in the `--pattern` option ([42db80a](https://github.com/readmeio/oas/commit/42db80a))
+* feat: adding new accessors for determining if an operation has required params (#615) ([c081d92](https://github.com/readmeio/oas/commit/c081d92)), closes [#615](https://github.com/readmeio/oas/issues/615)
+* feat: optionally generate friendlier operationIds (#602) ([6826164](https://github.com/readmeio/oas/commit/6826164)), closes [#602](https://github.com/readmeio/oas/issues/602)
+
+
+
 ## 17.8.0 (2022-03-02)
 
 * chore(deps-dev): bump @commitlint/cli from 16.1.0 to 16.2.1 (#612) ([e7364dd](https://github.com/readmeio/oas/commit/e7364dd)), closes [#612](https://github.com/readmeio/oas/issues/612)

package/dist/lib/find-schema-definition.js

@@ -8,6 +8,7 @@ var jsonpointer_1 = __importDefault(require("jsonpointer"));
 /**
  * Lookup a reference pointer within an OpenAPI definition and return the schema that it resolves to.
  *
+ * @deprecated
  * @param $ref Reference to look up a schema for.
  * @param definitions OpenAPI definition to look for the `$ref` pointer in.
  */

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

@@ -54,7 +54,8 @@ exports.types = {
     body: 'Body Params',
     cookie: 'Cookie Params',
     formData: 'Form Data',
-    header: 'Headers'
+    header: 'Headers',
+    metadata: 'Metadata'
 };
 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
@@ -77,19 +78,18 @@ function getSchemaVersionString(schema, api) {
 function cloneObject(obj) {
     return JSON.parse(JSON.stringify(obj));
 }
-/**
- * @param operation
- * @param api
- * @param globalDefaults
- */
-function getParametersAsJsonSchema(operation, api, globalDefaults) {
+function getParametersAsJsonSchema(operation, api, opts) {
     var _a;
-    if (globalDefaults === void 0) { globalDefaults = {}; }
     var hasCircularRefs = false;
     function refLogger() {
         hasCircularRefs = true;
     }
     function getDeprecated(schema, type) {
+        // If we wish to retain deprecated properties then we shouldn't split them out into the
+        // `deprecatedProps` object.
+        if (opts.retainDeprecatedProperties) {
+            return null;
+        }
         // If there's no properties, bail
         if (!schema || !schema.properties)
             return null;
@@ -107,7 +107,11 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
         });
         // We know this is the right type. todo: don't use as
         deprecatedBody.properties = allDeprecatedProps;
-        var deprecatedSchema = (0, openapi_to_json_schema_1["default"])(deprecatedBody, { globalDefaults: globalDefaults, prevSchemas: [], refLogger: refLogger });
+        var deprecatedSchema = (0, openapi_to_json_schema_1["default"])(deprecatedBody, {
+            globalDefaults: opts.globalDefaults,
+            prevSchemas: [],
+            refLogger: refLogger
+        });
         // 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) {
             return null;
@@ -152,7 +156,7 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
         // 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 = cloneObject(mediaTypeObject.schema);
-        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, { globalDefaults: globalDefaults, prevSchemas: prevSchemas, refLogger: refLogger });
+        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, { globalDefaults: opts.globalDefaults, prevSchemas: prevSchemas, refLogger: refLogger });
         // If this schema is **still** empty, don't bother returning it.
         if (!Object.keys(cleanedSchema).length) {
             return null;
@@ -177,7 +181,7 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
                 Object.keys(api.components[componentType]).forEach(function (schemaName) {
                     var componentSchema = cloneObject(api.components[componentType][schemaName]);
                     components[componentType][schemaName] = (0, openapi_to_json_schema_1["default"])(componentSchema, {
-                        globalDefaults: globalDefaults,
+                        globalDefaults: opts.globalDefaults,
                         refLogger: refLogger
                     });
                 });
@@ -187,7 +191,8 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
     }
     function transformParameters() {
         var operationParams = operation.getParameters();
-        return Object.keys(exports.types).map(function (type) {
+        var transformed = Object.keys(exports.types)
+            .map(function (type) {
             var required = [];
             // This `as` actually *could* be a ref, but we don't want refs to pass through here, so `.in` will never match `type`
             var parameters = operationParams.filter(function (param) { return param["in"] === type; });
@@ -212,7 +217,7 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
                         currentSchema.deprecated = current.deprecated;
                     schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
                         currentLocation: "/".concat(current.name),
-                        globalDefaults: globalDefaults,
+                        globalDefaults: opts.globalDefaults,
                         refLogger: refLogger
                     })), { 
                         // Note: this applies a $schema version to each field in the larger schema object. It's not really *correct*
@@ -255,7 +260,7 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
                                 currentSchema.deprecated = current.deprecated;
                             schema = __assign(__assign({}, (0, openapi_to_json_schema_1["default"])(currentSchema, {
                                 currentLocation: "/".concat(current.name),
-                                globalDefaults: globalDefaults,
+                                globalDefaults: opts.globalDefaults,
                                 refLogger: refLogger
                             })), { 
                                 // Note: this applies a $schema version to each field in the larger schema object. It's not really *correct*
@@ -286,7 +291,35 @@ function getParametersAsJsonSchema(operation, api, globalDefaults) {
                 schema: schema,
                 deprecatedProps: getDeprecated(schema, type)
             };
-        });
+        })
+            .filter(Boolean);
+        if (!opts.mergeIntoBodyAndMetadata) {
+            return transformed;
+        }
+        else if (!transformed.length) {
+            return [];
+        }
+        // If we want to merge parameters into a single metadata entry then we need to pull all
+        // available schemas and `deprecatedProps` (if we don't want to retain them via the
+        // `retainDeprecatedProps` option) under one roof.
+        var deprecatedProps = transformed.map(function (r) { var _a; return ((_a = r.deprecatedProps) === null || _a === void 0 ? void 0 : _a.schema) || null; }).filter(Boolean);
+        return [
+            {
+                type: 'metadata',
+                label: exports.types.metadata,
+                schema: {
+                    allOf: transformed.map(function (r) { return r.schema; })
+                },
+                deprecatedProps: deprecatedProps.length
+                    ? {
+                        type: 'metadata',
+                        schema: {
+                            allOf: deprecatedProps
+                        }
+                    }
+                    : null
+            },
+        ];
     }
     // If this operation neither has any parameters or a request body then we should return null because there won't be
     // any JSON Schema.

package/dist/operation.js

@@ -286,20 +286,33 @@ var Operation = /** @class */ (function () {
         return 'operationId' in this.schema;
     };
     /**
-     * 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.
+     * 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.camelCase Generate a JS method-friendly operation ID when one isn't present.
      */
-    Operation.prototype.getOperationId = function () {
+    Operation.prototype.getOperationId = function (opts) {
         if ('operationId' in this.schema) {
             return this.schema.operationId;
         }
-        var url = this.path
+        var method = this.method.toLowerCase();
+        var 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();
-        return "".concat(this.method.toLowerCase(), "_").concat(url);
+        if (opts === null || opts === void 0 ? void 0 : opts.camelCase) {
+            operationId = operationId.replace(/[^a-zA-Z0-9]+(.)/g, function (_, chr) { return chr.toUpperCase(); });
+            // 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)) {
+                return operationId;
+            }
+            operationId = operationId.charAt(0).toUpperCase() + operationId.slice(1);
+            return "".concat(method).concat(operationId);
+        }
+        return "".concat(method, "_").concat(operationId);
     };
     /**
      * Return an array of all tags, and their metadata, that exist on this operation.
@@ -358,14 +371,28 @@ var Operation = /** @class */ (function () {
         }
         return parameters;
     };
+    /**
+     * Determine if this operation has any required parameters.
+     *
+     */
+    Operation.prototype.hasRequiredParameters = function () {
+        return this.getParameters().some(function (param) { return 'required' in param && param.required; });
+    };
     /**
      * Convert the operation into an array of JSON Schema schemas for each available type of parameter available on the
      * operation.
      *
-     * @param globalDefaults Contains an object of user defined schema defaults.
+     * @param opts
+     * @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 (globalDefaults) {
-        return (0, get_parameters_as_json_schema_1["default"])(this, this.api, globalDefaults);
+    Operation.prototype.getParametersAsJsonSchema = function (opts) {
+        if (opts === void 0) { opts = {}; }
+        return (0, get_parameters_as_json_schema_1["default"])(this, this.api, opts);
     };
     /**
      * Get a single response for this status code, formatted as JSON schema.
@@ -407,6 +434,33 @@ var Operation = /** @class */ (function () {
         }
         return Object.keys(requestBody.content);
     };
+    /**
+     * Determine if this operation has a required request body.
+     *
+     */
+    Operation.prototype.hasRequiredRequestBody = function () {
+        if (!this.hasRequestBody()) {
+            return false;
+        }
+        var requestBody = this.schema.requestBody;
+        if (RMOAS.isRef(requestBody)) {
+            return false;
+        }
+        if (requestBody.required) {
+            return true;
+        }
+        // The OpenAPI spec isn't clear on the differentiation between schema `required` and
+        // `requestBody.required` because you can have required top-level schema properties but a
+        // non-required requestBody that negates each other.
+        //
+        // To kind of work ourselves around this and present a better QOL for this accessor, if at this
+        // 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()
+            .filter(function (js) { return ['body', 'formData'].includes(js.type); })
+            .find(function (js) { return js.schema && Array.isArray(js.schema.required) && js.schema.required.length; });
+    };
     /**
      * Retrieve a specific request body content schema off this operation.
      *

package/dist/utils.js

@@ -5,14 +5,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 exports.__esModule = true;
 exports.supportedMethods = void 0;
 var find_schema_definition_1 = __importDefault(require("./lib/find-schema-definition"));
-var get_schema_1 = __importDefault(require("./lib/get-schema"));
 var matches_mimetype_1 = __importDefault(require("./lib/matches-mimetype"));
 var get_parameters_as_json_schema_1 = require("./operation/get-parameters-as-json-schema");
 var supportedMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
 exports.supportedMethods = supportedMethods;
 exports["default"] = {
     findSchemaDefinition: find_schema_definition_1["default"],
-    getSchema: get_schema_1["default"],
     jsonSchemaTypes: get_parameters_as_json_schema_1.types,
     matchesMimeType: matches_mimetype_1["default"]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "17.8.0",
+  "version": "18.0.1",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -37,10 +37,11 @@
   "scripts": {
     "build": "tsc",
     "lint": "eslint . --ext .js,.ts",
+    "lint:docs": "alex . .github/",
     "prebuild": "rm -rf dist/ @types/",
     "prepack": "npm run build",
     "prepare": "husky install",
-    "pretest": "npm run lint",
+    "pretest": "npm run lint && npm run lint:docs",
     "prettier": "prettier --list-different --write \"./**/**.{js,ts}\"",
     "release": "npx conventional-changelog-cli -i CHANGELOG.md -s && git add CHANGELOG.md",
     "test": "tsc; jest --coverage",
@@ -67,11 +68,12 @@
   "devDependencies": {
     "@commitlint/cli": "^16.0.1",
     "@commitlint/config-conventional": "^16.0.0",
-    "@readme/eslint-config": "^8.4.1",
+    "@readme/eslint-config": "^8.5.0",
     "@readme/oas-examples": "^4.3.2",
     "@types/jest": "^27.0.2",
     "@types/json-schema-merge-allof": "^0.6.1",
     "@types/memoizee": "^0.4.6",
+    "alex": "^10.0.0",
     "eslint": "^8.6.0",
     "eslint-plugin-jsdoc": "^37.0.3",
     "husky": "^7.0.2",

package/src/cli/lib/utils.js

@@ -53,7 +53,7 @@ exports.findSwagger = async function (info, cb) {
     format: '.json',
     scope: info.opts.scope,
     base,
-    pattern: info.ops.pattern || null,
+    pattern: info.opts.pattern || null,
   }).catch(err => {
     console.error(err);
     process.exit(1);

package/src/lib/find-schema-definition.ts

@@ -4,6 +4,7 @@ import jsonpointer from 'jsonpointer';
 /**
  * Lookup a reference pointer within an OpenAPI definition and return the schema that it resolves to.
  *
+ * @deprecated
  * @param $ref Reference to look up a schema for.
  * @param definitions OpenAPI definition to look for the `$ref` pointer in.
  */

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

@@ -28,6 +28,7 @@ export const types: Record<keyof RMOAS.OASDocument, string> = {
   cookie: 'Cookie Params',
   formData: 'Form Data',
   header: 'Headers',
+  metadata: 'Metadata', // This a special type reserved for https://npm.im/api
 };
 
 function getSchemaVersionString(schema: SchemaObject, api: OASDocument): string {
@@ -56,12 +57,15 @@ function cloneObject<T>(obj: T): T {
   return JSON.parse(JSON.stringify(obj));
 }
 
-/**
- * @param operation
- * @param api
- * @param globalDefaults
- */
-export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, globalDefaults = {}) {
+export default function getParametersAsJsonSchema(
+  operation: Operation,
+  api: OASDocument,
+  opts?: {
+    globalDefaults?: Record<string, unknown>;
+    mergeIntoBodyAndMetadata?: boolean;
+    retainDeprecatedProperties?: boolean;
+  }
+) {
   let hasCircularRefs = false;
 
   function refLogger() {
@@ -69,6 +73,12 @@ export default function getParametersAsJsonSchema(operation: Operation, api: OAS
   }
 
   function getDeprecated(schema: SchemaObject, type: string) {
+    // If we wish to retain deprecated properties then we shouldn't split them out into the
+    // `deprecatedProps` object.
+    if (opts.retainDeprecatedProperties) {
+      return null;
+    }
+
     // If there's no properties, bail
     if (!schema || !schema.properties) return null;
     // Clone the original schema so this doesn't interfere with it
@@ -88,7 +98,11 @@ export default function getParametersAsJsonSchema(operation: Operation, api: OAS
 
     // We know this is the right type. todo: don't use as
     (deprecatedBody.properties as Record<string, SchemaObject>) = allDeprecatedProps;
-    const deprecatedSchema = toJSONSchema(deprecatedBody, { globalDefaults, prevSchemas: [], refLogger });
+    const deprecatedSchema = toJSONSchema(deprecatedBody, {
+      globalDefaults: opts.globalDefaults,
+      prevSchemas: [],
+      refLogger,
+    });
 
     // 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) {
@@ -142,7 +156,7 @@ export default function getParametersAsJsonSchema(operation: Operation, api: OAS
     // 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, prevSchemas, refLogger });
+    const cleanedSchema = toJSONSchema(requestSchema, { globalDefaults: opts.globalDefaults, prevSchemas, refLogger });
 
     // If this schema is **still** empty, don't bother returning it.
     if (!Object.keys(cleanedSchema).length) {
@@ -176,7 +190,7 @@ export default function getParametersAsJsonSchema(operation: Operation, api: OAS
         Object.keys(api.components[componentType]).forEach(schemaName => {
           const componentSchema = cloneObject(api.components[componentType][schemaName]);
           components[componentType][schemaName] = toJSONSchema(componentSchema as RMOAS.SchemaObject, {
-            globalDefaults,
+            globalDefaults: opts.globalDefaults,
             refLogger,
           });
         });
@@ -189,118 +203,148 @@ export default function getParametersAsJsonSchema(operation: Operation, api: OAS
   function transformParameters(): SchemaWrapper[] {
     const operationParams = operation.getParameters();
 
-    return Object.keys(types).map(type => {
-      const required: string[] = [];
+    const transformed = Object.keys(types)
+      .map(type => {
+        const required: string[] = [];
 
-      // This `as` actually *could* be a ref, but we don't want refs to pass through here, so `.in` will never match `type`
-      const parameters = operationParams.filter(param => (param as RMOAS.ParameterObject).in === type);
-      if (parameters.length === 0) {
-        return null;
-      }
+        // This `as` actually *could* be a ref, but we don't want refs to pass through here, so `.in` will never match `type`
+        const parameters = operationParams.filter(param => (param as RMOAS.ParameterObject).in === type);
+        if (parameters.length === 0) {
+          return null;
+        }
 
-      const properties = parameters.reduce((prev: Record<string, SchemaObject>, current: RMOAS.ParameterObject) => {
-        let schema: SchemaObject = {};
-        if ('schema' in current) {
-          const currentSchema: SchemaObject = current.schema ? cloneObject(current.schema) : {};
-
-          if (current.example) {
-            // `example` can be present outside of the `schema` block so if it's there we should pull it in so it can be
-            // handled and returned if it's valid.
-            currentSchema.example = current.example;
-          } else if (current.examples) {
-            // `examples` isn't actually supported here in OAS 3.0, but we might as well support it because `examples` is
-            // JSON Schema and that's fully supported in OAS 3.1.
-            currentSchema.examples = current.examples as unknown as unknown[];
-          }
+        const properties = parameters.reduce((prev: Record<string, SchemaObject>, current: RMOAS.ParameterObject) => {
+          let schema: SchemaObject = {};
+          if ('schema' in current) {
+            const currentSchema: SchemaObject = current.schema ? cloneObject(current.schema) : {};
+
+            if (current.example) {
+              // `example` can be present outside of the `schema` block so if it's there we should pull it in so it can be
+              // handled and returned if it's valid.
+              currentSchema.example = current.example;
+            } else if (current.examples) {
+              // `examples` isn't actually supported here in OAS 3.0, but we might as well support it because `examples` is
+              // JSON Schema and that's fully supported in OAS 3.1.
+              currentSchema.examples = current.examples as unknown as unknown[];
+            }
 
-          if (current.deprecated) currentSchema.deprecated = current.deprecated;
-
-          schema = {
-            ...toJSONSchema(currentSchema, {
-              currentLocation: `/${current.name}`,
-              globalDefaults,
-              refLogger,
-            }),
-            // 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) {
-            let contentType;
-            if (contentKeys.length === 1) {
-              contentType = contentKeys[0];
-            } else {
-              // We should always try to prioritize `application/json` over any other possible content that might be present
-              // on this schema.
-              const jsonLikeContentTypes = contentKeys.filter(k => isJSON(k));
-              if (jsonLikeContentTypes.length) {
-                contentType = jsonLikeContentTypes[0];
-              } else {
+            if (current.deprecated) currentSchema.deprecated = current.deprecated;
+
+            schema = {
+              ...toJSONSchema(currentSchema, {
+                currentLocation: `/${current.name}`,
+                globalDefaults: opts.globalDefaults,
+                refLogger,
+              }),
+              // 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) {
+              let contentType;
+              if (contentKeys.length === 1) {
                 contentType = contentKeys[0];
+              } else {
+                // We should always try to prioritize `application/json` over any other possible content that might be present
+                // on this schema.
+                const jsonLikeContentTypes = contentKeys.filter(k => isJSON(k));
+                if (jsonLikeContentTypes.length) {
+                  contentType = jsonLikeContentTypes[0];
+                } else {
+                  contentType = contentKeys[0];
+                }
               }
-            }
 
-            if (typeof current.content[contentType] === 'object' && 'schema' in current.content[contentType]) {
-              const currentSchema: SchemaObject = current.content[contentType].schema
-                ? cloneObject(current.content[contentType].schema)
-                : {};
-
-              if (current.example) {
-                // `example` can be present outside of the `schema` block so if it's there we should pull it in so it can be
-                // handled and returned if it's valid.
-                currentSchema.example = current.example;
-              } else if (current.examples) {
-                // `examples` isn't actually supported here in OAS 3.0, but we might as well support it because `examples` is
-                // JSON Schema and that's fully supported in OAS 3.1.
-                currentSchema.examples = current.examples as unknown as unknown[];
+              if (typeof current.content[contentType] === 'object' && 'schema' in current.content[contentType]) {
+                const currentSchema: SchemaObject = current.content[contentType].schema
+                  ? cloneObject(current.content[contentType].schema)
+                  : {};
+
+                if (current.example) {
+                  // `example` can be present outside of the `schema` block so if it's there we should pull it in so it can be
+                  // handled and returned if it's valid.
+                  currentSchema.example = current.example;
+                } else if (current.examples) {
+                  // `examples` isn't actually supported here in OAS 3.0, but we might as well support it because `examples` is
+                  // JSON Schema and that's fully supported in OAS 3.1.
+                  currentSchema.examples = current.examples as unknown as unknown[];
+                }
+
+                if (current.deprecated) currentSchema.deprecated = current.deprecated;
+
+                schema = {
+                  ...toJSONSchema(currentSchema, {
+                    currentLocation: `/${current.name}`,
+                    globalDefaults: opts.globalDefaults,
+                    refLogger,
+                  }),
+                  // 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),
+                };
               }
-
-              if (current.deprecated) currentSchema.deprecated = current.deprecated;
-
-              schema = {
-                ...toJSONSchema(currentSchema, {
-                  currentLocation: `/${current.name}`,
-                  globalDefaults,
-                  refLogger,
-                }),
-                // 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),
-              };
             }
           }
-        }
 
-        // Parameter descriptions don't exist in `current.schema` so `constructSchema` will never have access to it.
-        if (current.description) {
-          schema.description = current.description;
-        }
+          // Parameter descriptions don't exist in `current.schema` so `constructSchema` will never have access to it.
+          if (current.description) {
+            schema.description = current.description;
+          }
 
-        prev[current.name] = schema;
+          prev[current.name] = schema;
 
-        if (current.required) {
-          required.push(current.name);
-        }
+          if (current.required) {
+            required.push(current.name);
+          }
 
-        return prev;
-      }, {});
-
-      // This typing is technically WRONG :( but it's the best we can do for now.
-      const schema: OpenAPIV3_1.SchemaObject = {
-        type: 'object',
-        properties: properties as Record<string, OpenAPIV3_1.SchemaObject>,
-        required,
-      };
-
-      return {
-        type,
-        label: types[type],
-        schema,
-        deprecatedProps: getDeprecated(schema, type),
-      };
-    });
+          return prev;
+        }, {});
+
+        // This typing is technically WRONG :( but it's the best we can do for now.
+        const schema: OpenAPIV3_1.SchemaObject = {
+          type: 'object',
+          properties: properties as Record<string, OpenAPIV3_1.SchemaObject>,
+          required,
+        };
+
+        return {
+          type,
+          label: types[type],
+          schema,
+          deprecatedProps: getDeprecated(schema, type),
+        };
+      })
+      .filter(Boolean);
+
+    if (!opts.mergeIntoBodyAndMetadata) {
+      return transformed;
+    } else if (!transformed.length) {
+      return [];
+    }
+
+    // If we want to merge parameters into a single metadata entry then we need to pull all
+    // available schemas and `deprecatedProps` (if we don't want to retain them via the
+    // `retainDeprecatedProps` option) under one roof.
+    const deprecatedProps = transformed.map(r => r.deprecatedProps?.schema || null).filter(Boolean);
+    return [
+      {
+        type: 'metadata',
+        label: types.metadata,
+        schema: {
+          allOf: transformed.map(r => r.schema),
+        } as SchemaObject,
+        deprecatedProps: deprecatedProps.length
+          ? {
+              type: 'metadata',
+              schema: {
+                allOf: deprecatedProps,
+              } as SchemaObject,
+            }
+          : null,
+      },
+    ];
   }
 
   // If this operation neither has any parameters or a request body then we should return null because there won't be

package/src/operation.ts

@@ -323,22 +323,38 @@ 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.
+   * 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.camelCase Generate a JS method-friendly operation ID when one isn't present.
    */
-  getOperationId(): string {
+  getOperationId(opts?: { camelCase: boolean }): string {
     if ('operationId' in this.schema) {
       return this.schema.operationId;
     }
 
-    const url = this.path
+    const method = this.method.toLowerCase();
+    let 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();
 
-    return `${this.method.toLowerCase()}_${url}`;
+    if (opts?.camelCase) {
+      operationId = operationId.replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase());
+
+      // 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)) {
+        return operationId;
+      }
+
+      operationId = operationId.charAt(0).toUpperCase() + operationId.slice(1);
+      return `${method}${operationId}`;
+    }
+
+    return `${method}_${operationId}`;
   }
 
   /**
@@ -405,14 +421,34 @@ export default class Operation {
     return parameters;
   }
 
+  /**
+   * Determine if this operation has any required parameters.
+   *
+   */
+  hasRequiredParameters() {
+    return this.getParameters().some(param => 'required' in param && param.required);
+  }
+
   /**
    * Convert the operation into an array of JSON Schema schemas for each available type of parameter available on the
    * operation.
    *
-   * @param globalDefaults Contains an object of user defined schema defaults.
-   */
-  getParametersAsJsonSchema(globalDefaults?: Record<string, unknown>) {
-    return getParametersAsJsonSchema(this, this.api, globalDefaults);
+   * @param opts
+   * @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: {
+      globalDefaults?: Record<string, unknown>;
+      mergeIntoBodyAndMetadata?: boolean;
+      retainDeprecatedProperties?: boolean;
+    } = {}
+  ) {
+    return getParametersAsJsonSchema(this, this.api, opts);
   }
 
   /**
@@ -461,6 +497,37 @@ export default class Operation {
     return Object.keys(requestBody.content);
   }
 
+  /**
+   * Determine if this operation has a required request body.
+   *
+   */
+  hasRequiredRequestBody() {
+    if (!this.hasRequestBody()) {
+      return false;
+    }
+
+    const requestBody = this.schema.requestBody;
+    if (RMOAS.isRef(requestBody)) {
+      return false;
+    }
+
+    if (requestBody.required) {
+      return true;
+    }
+
+    // The OpenAPI spec isn't clear on the differentiation between schema `required` and
+    // `requestBody.required` because you can have required top-level schema properties but a
+    // non-required requestBody that negates each other.
+    //
+    // To kind of work ourselves around this and present a better QOL for this accessor, if at this
+    // 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()
+      .filter(js => ['body', 'formData'].includes(js.type))
+      .find(js => js.schema && Array.isArray(js.schema.required) && js.schema.required.length);
+  }
+
   /**
    * Retrieve a specific request body content schema off this operation.
    *

package/src/rmoas.types.ts

@@ -153,6 +153,7 @@ export type SchemaObject = (
   | JSONSchema
 ) & {
   // TODO: We should split this into one type for v3 and one type for v3.1 to ensure type accuracy.
+  $schema?: string;
   deprecated?: boolean;
   readOnly?: boolean;
   writeOnly?: boolean;

package/src/utils.ts

@@ -1,5 +1,4 @@
 import findSchemaDefinition from './lib/find-schema-definition';
-import getSchema from './lib/get-schema';
 import matchesMimeType from './lib/matches-mimetype';
 import { types as jsonSchemaTypes } from './operation/get-parameters-as-json-schema';
 
@@ -7,7 +6,6 @@ const supportedMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'he
 
 export default {
   findSchemaDefinition,
-  getSchema,
   jsonSchemaTypes,
   matchesMimeType,
 };

package/@types/lib/get-schema.d.ts

@@ -1,17 +0,0 @@
-import type * as RMOAS from '../rmoas.types';
-/**
- * Retrieves the schema of the first media type defined in the `content` of the path operation or returns the reference
- * if there's no Request Body Object.
- *
- * If the reference pointer looks like a `requestBodies` reference, then we also do a lookup for the actual schema.
- *
- * @deprecated
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8}
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields-8}
- * @param operation Operation to look for a primary requestBody schema in.
- * @param api The API definition that this operation exists within.
- */
-export default function getSchema(operation: RMOAS.OperationObject, api?: RMOAS.OASDocument | Record<string, Record<string, RMOAS.SchemaObject>>): {
-    type: string;
-    schema: any;
-};

package/CODE_OF_CONDUCT.md

@@ -1,128 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
-  overall community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[support+coc@readme.io](mailto:support+coc@readme.io).
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series
-of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or
-permanent ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within
-the community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct
-enforcement ladder](https://github.com/mozilla/diversity).
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.

package/SECURITY.md

@@ -1,12 +0,0 @@
-# Security Policy
-
-## Reporting a Vulnerability
-
-If there are any vulnerabilities in `oas`, don't hesitate to _report them_.
-
-Please email security@readme.io and describe what you've found.
-
-- If you have a fix, explain or attach it.
-- In the near time, expect a reply with the required steps. Also, there may be a demand for a pull request which include the fixes.
-
-> You should not disclose the vulnerability publicly if you haven't received an answer in some weeks. If the vulnerability is rejected, you may post it publicly within some hour of rejection, unless the rejection is withdrawn within that time period. After the vulnerability has been fixed, you may disclose the vulnerability details publicly over some days.

package/dist/lib/get-schema.js

@@ -1,45 +0,0 @@
-"use strict";
-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 find_schema_definition_1 = __importDefault(require("./find-schema-definition"));
-/**
- * Retrieves the schema of the first media type defined in the `content` of the path operation or returns the reference
- * if there's no Request Body Object.
- *
- * If the reference pointer looks like a `requestBodies` reference, then we also do a lookup for the actual schema.
- *
- * @deprecated
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8}
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields-8}
- * @param operation Operation to look for a primary requestBody schema in.
- * @param api The API definition that this operation exists within.
- */
-function getSchema(operation, api) {
-    try {
-        if ((0, rmoas_types_1.isRef)(operation.requestBody)) {
-            if (operation.requestBody.$ref.match(/^#\/components\/requestBodies\/.*$/)) {
-                return getSchema({
-                    requestBody: (0, find_schema_definition_1["default"])(operation.requestBody.$ref, api)
-                });
-            }
-        }
-        var requestBody = operation.requestBody;
-        if (requestBody.content) {
-            var type = Object.keys(requestBody.content)[0];
-            return {
-                type: type,
-                schema: requestBody.content[type]
-            };
-        }
-        return {
-            type: 'application/json',
-            schema: requestBody
-        };
-    }
-    catch (e) { } // eslint-disable-line no-empty
-    return undefined;
-}
-exports["default"] = getSchema;

package/src/lib/get-schema.ts

@@ -1,50 +0,0 @@
-import type * as RMOAS from '../rmoas.types';
-import { isRef } from '../rmoas.types';
-import findSchemaDefinition from './find-schema-definition';
-
-/**
- * Retrieves the schema of the first media type defined in the `content` of the path operation or returns the reference
- * if there's no Request Body Object.
- *
- * If the reference pointer looks like a `requestBodies` reference, then we also do a lookup for the actual schema.
- *
- * @deprecated
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8}
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields-8}
- * @param operation Operation to look for a primary requestBody schema in.
- * @param api The API definition that this operation exists within.
- */
-export default function getSchema(
-  operation: RMOAS.OperationObject,
-  api?: RMOAS.OASDocument | Record<string /* schemaType */, Record<string, RMOAS.SchemaObject>>
-): {
-  type: string;
-  schema: any; // @fixme give this a better type
-} {
-  try {
-    if (isRef(operation.requestBody)) {
-      if (operation.requestBody.$ref.match(/^#\/components\/requestBodies\/.*$/)) {
-        return getSchema({
-          requestBody: findSchemaDefinition(operation.requestBody.$ref, api),
-        } as RMOAS.OperationObject);
-      }
-    }
-
-    const requestBody = operation.requestBody as RMOAS.RequestBodyObject;
-    if (requestBody.content) {
-      const type = Object.keys(requestBody.content)[0];
-
-      return {
-        type,
-        schema: requestBody.content[type],
-      };
-    }
-
-    return {
-      type: 'application/json',
-      schema: requestBody,
-    };
-  } catch (e) {} // eslint-disable-line no-empty
-
-  return undefined;
-}