oas 17.5.0 → 17.7.2

package/@types/lib/dedupe-common-parameters.d.ts

@@ -0,0 +1,9 @@
+import * as RMOAS from '../rmoas.types';
+/**
+ * With an array of common parameters filter down them to what isn't already present in a list of non-common
+ * parameters.
+ *
+ * @param parameters
+ * @param commonParameters
+ */
+export default function dedupeCommonParameters(parameters: RMOAS.ParameterObject[], commonParameters: RMOAS.ParameterObject[]): import("openapi-types").OpenAPIV3.ParameterObject[];

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

@@ -5,6 +5,7 @@ import type * as RMOAS from '../rmoas.types';
  *
  * 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.

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

@@ -1,4 +1,5 @@
-import type { OASDocument, OperationObject, SchemaObject } from '../rmoas.types';
+import type { OASDocument, SchemaObject } from '../rmoas.types';
+import type Operation from '../operation';
 import * as RMOAS from '../rmoas.types';
 export declare type SchemaWrapper = {
     $schema?: string;
@@ -17,9 +18,8 @@ export declare const types: {
     [key: keyof RMOAS.OASDocument]: string;
 };
 /**
- * @param path
  * @param operation
  * @param api
  * @param globalDefaults
  */
-export default function getParametersAsJsonSchema(path: string, operation: OperationObject, api: OASDocument, globalDefaults?: {}): SchemaWrapper[];
+export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, globalDefaults?: {}): SchemaWrapper[];

package/@types/operation.d.ts

@@ -1,4 +1,3 @@
-import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { CallbackExamples } from './operation/get-callback-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
@@ -100,10 +99,14 @@ export default class Operation {
      *
      */
     isDeprecated(): boolean;
+    /**
+     * Determine if the operation has any (non-request body) parameters.
+     *
+     */
+    hasParameters(): boolean;
     /**
      * Return the parameters (non-request body) on the operation.
      *
-     * @todo This should also pull in common params.
      */
     getParameters(): Array<RMOAS.ParameterObject>;
     /**
@@ -134,14 +137,25 @@ export default class Operation {
      *
      */
     hasRequestBody(): boolean;
+    /**
+     * Retrieve the list of all available media types that the operations request body can accept.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
+     */
+    getRequestBodyMediaTypes(): string[];
     /**
      * Retrieve a specific request body content schema off this operation.
      *
+     * If no media type is supplied this will return either the first available JSON-like request body, or the first
+     * available if there are no JSON-like media types present. When this return comes back it's in the form of an array
+     * with the first key being the selected media type, followed by the media type object in question.
+     *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
      * @param mediaType Specific request body media type to retrieve if present.
      */
-    getRequestBody(mediaType: string): false | OpenAPIV3.MediaTypeObject | OpenAPIV3_1.MediaTypeObject;
+    getRequestBody(mediaType?: string): false | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject];
     /**
      * Retrieve an array of request body examples that this operation has.
      *
@@ -219,6 +233,7 @@ export declare class Callback extends Operation {
     getIdentifier(): string;
     getSummary(): string;
     getDescription(): string;
+    getParameters(): Array<RMOAS.ParameterObject>;
 }
 export declare class Webhook extends Operation {
 }

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

@@ -41,6 +41,15 @@ export declare type ServerVariableObject = OpenAPIV3.ServerVariableObject | Open
 export declare type ServerVariablesObject = {
     [variable: string]: ServerVariableObject;
 };
+export declare type ServerVariable = Record<string, string | number | Array<{
+    default?: string | number;
+}> | {
+    default?: string | number;
+} | Record<string, never>>;
+export declare type Servers = {
+    selected: number;
+    variables: ServerVariable;
+};
 /**
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject}

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## <small>17.7.2 (2022-02-02)</small>
+
+* chore(deps-dev): bump @commitlint/cli from 16.0.1 to 16.1.0 (#591) ([a46f0ab](https://github.com/readmeio/oas/commit/a46f0ab)), closes [#591](https://github.com/readmeio/oas/issues/591)
+* chore(deps-dev): bump @readme/eslint-config from 8.1.2 to 8.2.0 (#592) ([55554dc](https://github.com/readmeio/oas/commit/55554dc)), closes [#592](https://github.com/readmeio/oas/issues/592)
+* chore(deps-dev): bump @readme/oas-examples from 4.3.2 to 4.4.0 (#588) ([fbdef2b](https://github.com/readmeio/oas/commit/fbdef2b)), closes [#588](https://github.com/readmeio/oas/issues/588)
+* chore(deps-dev): bump @types/memoizee from 0.4.6 to 0.4.7 (#596) ([ccd1a3c](https://github.com/readmeio/oas/commit/ccd1a3c)), closes [#596](https://github.com/readmeio/oas/issues/596)
+* chore(deps-dev): bump eslint from 8.6.0 to 8.8.0 (#593) ([d681a62](https://github.com/readmeio/oas/commit/d681a62)), closes [#593](https://github.com/readmeio/oas/issues/593)
+* chore(deps-dev): bump eslint-plugin-jsdoc from 37.5.0 to 37.7.0 (#594) ([aa525ab](https://github.com/readmeio/oas/commit/aa525ab)), closes [#594](https://github.com/readmeio/oas/issues/594)
+* chore(deps-dev): bump jest from 27.4.5 to 27.4.7 (#589) ([475c40b](https://github.com/readmeio/oas/commit/475c40b)), closes [#589](https://github.com/readmeio/oas/issues/589)
+* chore(deps-dev): bump ts-jest from 27.1.2 to 27.1.3 (#595) ([c2ca154](https://github.com/readmeio/oas/commit/c2ca154)), closes [#595](https://github.com/readmeio/oas/issues/595)
+* chore(deps-dev): bump typescript from 4.5.4 to 4.5.5 (#590) ([26bc893](https://github.com/readmeio/oas/commit/26bc893)), closes [#590](https://github.com/readmeio/oas/issues/590)
+* chore(deps): bump swagger-inline from 5.0.2 to 5.0.4 (#597) ([c173d1e](https://github.com/readmeio/oas/commit/c173d1e)), closes [#597](https://github.com/readmeio/oas/issues/597)
+
+
+
+## <small>17.7.1 (2022-01-31)</small>
+
+* fix: bumping oas-normalize to fix a bug with header content validation (#587) ([c5594ee](https://github.com/readmeio/oas/commit/c5594ee)), closes [#587](https://github.com/readmeio/oas/issues/587)
+
+
+
+## 17.7.0 (2022-01-27)
+
+* fix: show response headers w/o mediaType content (#584) ([a9bccd1](https://github.com/readmeio/oas/commit/a9bccd1)), closes [#584](https://github.com/readmeio/oas/issues/584)
+
+
+
+## 17.6.0 (2022-01-26)
+
+* chore: add server variable typescript types (#586) ([0868626](https://github.com/readmeio/oas/commit/0868626)), closes [#586](https://github.com/readmeio/oas/issues/586)
+* chore(deps): bumping node-fetch ([0f7dbe1](https://github.com/readmeio/oas/commit/0f7dbe1))
+* fix: funky typing with how we extract examples during JSON Schema generation (#585) ([15ece60](https://github.com/readmeio/oas/commit/15ece60)), closes [#585](https://github.com/readmeio/oas/issues/585)
+* refactor: cleaning up the messy `getSchema` library and other improvements (#581) ([f3f0e43](https://github.com/readmeio/oas/commit/f3f0e43)), closes [#581](https://github.com/readmeio/oas/issues/581)
+* refactor: use default for samples over generic type (#582) ([c1b1c66](https://github.com/readmeio/oas/commit/c1b1c66)), closes [#582](https://github.com/readmeio/oas/issues/582)
+
+
+
 ## 17.5.0 (2022-01-12)
 
 * feat: addition of a getRequestBody accessor (#580) ([88b0b33](https://github.com/readmeio/oas/commit/88b0b33)), closes [#580](https://github.com/readmeio/oas/issues/580)

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

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+exports.__esModule = true;
+var RMOAS = __importStar(require("../rmoas.types"));
+/**
+ * With an array of common parameters filter down them to what isn't already present in a list of non-common
+ * parameters.
+ *
+ * @param parameters
+ * @param commonParameters
+ */
+function dedupeCommonParameters(parameters, commonParameters) {
+    return commonParameters.filter(function (param) {
+        return !parameters.find(function (param2) {
+            if (param.name && param2.name) {
+                return param.name === param2.name && param["in"] === param2["in"];
+            }
+            else if (RMOAS.isRef(param) && RMOAS.isRef(param2)) {
+                return param.$ref === param2.$ref;
+            }
+            return false;
+        });
+    });
+}
+exports["default"] = dedupeCommonParameters;

package/dist/lib/get-schema.js

@@ -11,6 +11,7 @@ var find_schema_definition_1 = __importDefault(require("./find-schema-definition
  *
  * 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.

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

@@ -180,19 +180,11 @@ function searchForExampleByPointer(pointer, examples) {
                 schema = schema.example;
             }
             else {
-                var keys = Object.keys(schema.examples);
-                if (!keys.length) {
+                if (!Array.isArray(schema.examples) || !schema.examples.length) {
                     continue;
                 }
                 // Prevent us from crashing if `examples` is a completely empty object.
-                var ex = schema.examples[keys.shift()];
-                if (typeof ex !== 'object' || Array.isArray(ex)) {
-                    continue;
-                }
-                else if (!('value' in ex)) {
-                    continue;
-                }
-                schema = ex.value;
+                schema = schema.examples.shift();
             }
             try {
                 example = jsonpointer_1["default"].get(schema, pointers[i]);
@@ -384,7 +376,11 @@ function toJSONSchema(data, opts) {
                             reshapedExamples_1 = true;
                         }
                         else {
-                            prevSchemas.push({ examples: schema.examples });
+                            // If this example is neither a primitive or an array we should dump it into the `prevSchemas` array
+                            // because we might be able to extract an example from it further downstream.
+                            prevSchemas.push({
+                                example: example.value
+                            });
                         }
                     }
                 });

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

@@ -34,7 +34,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 exports.types = void 0;
-var get_schema_1 = __importDefault(require("../lib/get-schema"));
 var matches_mimetype_1 = __importDefault(require("../lib/matches-mimetype"));
 var openapi_to_json_schema_1 = __importDefault(require("../lib/openapi-to-json-schema"));
 var RMOAS = __importStar(require("../rmoas.types"));
@@ -75,12 +74,11 @@ function cloneObject(obj) {
     return JSON.parse(JSON.stringify(obj));
 }
 /**
- * @param path
  * @param operation
  * @param api
  * @param globalDefaults
  */
-function getParametersAsJsonSchema(path, operation, api, globalDefaults) {
+function getParametersAsJsonSchema(operation, api, globalDefaults) {
     var _a;
     if (globalDefaults === void 0) { globalDefaults = {}; }
     var hasCircularRefs = false;
@@ -126,29 +124,33 @@ function getParametersAsJsonSchema(path, operation, api, globalDefaults) {
     /**
      *
      */
-    function getRequestBody() {
-        var schema = (0, get_schema_1["default"])(operation, api);
-        if (!schema || !schema.schema)
+    function transformRequestBody() {
+        var requestBody = operation.getRequestBody();
+        if (!requestBody || !Array.isArray(requestBody))
             return null;
-        var type = schema.type === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
-        var requestBody = schema.schema;
+        var mediaType = requestBody[0], mediaTypeObject = requestBody[1];
+        var type = mediaType === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
         // If this schema is completely empty, don't bother processing it.
-        if (Object.keys(requestBody.schema).length === 0) {
+        if (!Object.keys(mediaTypeObject.schema).length) {
             return null;
         }
-        var examples = [];
-        if ('example' in requestBody) {
-            examples.push({ example: requestBody.example });
+        var prevSchemas = [];
+        if ('example' in mediaTypeObject) {
+            prevSchemas.push({ example: mediaTypeObject.example });
         }
-        else if ('examples' in requestBody) {
-            examples.push({ examples: requestBody.examples });
+        else if ('examples' in mediaTypeObject) {
+            prevSchemas.push({
+                examples: Object.values(mediaTypeObject.examples)
+                    .map(function (example) { return example.value; })
+                    .filter(function (val) { return val !== undefined; })
+            });
         }
         // 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(requestBody.schema);
-        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, { globalDefaults: globalDefaults, prevSchemas: examples, refLogger: refLogger });
+        var requestSchema = cloneObject(mediaTypeObject.schema);
+        var cleanedSchema = (0, openapi_to_json_schema_1["default"])(requestSchema, { globalDefaults: globalDefaults, prevSchemas: prevSchemas, refLogger: refLogger });
         // If this schema is **still** empty, don't bother returning it.
-        if (Object.keys(cleanedSchema).length === 0) {
+        if (!Object.keys(cleanedSchema).length) {
             return null;
         }
         return {
@@ -158,13 +160,7 @@ function getParametersAsJsonSchema(path, operation, api, globalDefaults) {
             deprecatedProps: getDeprecated(cleanedSchema, type)
         };
     }
-    function getCommonParams() {
-        if (api && 'paths' in api && path in api.paths && 'parameters' in api.paths[path]) {
-            return api.paths[path].parameters;
-        }
-        return [];
-    }
-    function getComponents() {
+    function transformComponents() {
         if (!('components' in api)) {
             return false;
         }
@@ -185,23 +181,8 @@ function getParametersAsJsonSchema(path, operation, api, globalDefaults) {
         });
         return components;
     }
-    function getParameters() {
-        var operationParams = operation.parameters || [];
-        var commonParams = getCommonParams();
-        if (commonParams.length !== 0) {
-            var commonParamsNotInParams = commonParams.filter(function (param) {
-                return !operationParams.find(function (param2) {
-                    if (param.name && param2.name) {
-                        return param.name === param2.name && param["in"] === param2["in"];
-                    }
-                    else if (RMOAS.isRef(param) && RMOAS.isRef(param2)) {
-                        return param.$ref === param2.$ref;
-                    }
-                    return false;
-                });
-            });
-            operationParams = operationParams.concat(commonParamsNotInParams || []);
-        }
+    function transformParameters() {
+        var operationParams = operation.getParameters();
         return 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`
@@ -303,14 +284,15 @@ function getParametersAsJsonSchema(path, operation, api, globalDefaults) {
             };
         });
     }
-    var hasRequestBody = !!operation.requestBody;
-    var hasParameters = !!(operation.parameters && operation.parameters.length !== 0);
-    if (!hasParameters && !hasRequestBody && getCommonParams().length === 0)
+    // If this operation neither has any parameters or a request body then we should return null because there won't be
+    // any JSON Schema.
+    if (!operation.hasParameters() && !operation.hasRequestBody()) {
         return null;
-    var components = getComponents();
+    }
+    var components = transformComponents();
     var typeKeys = Object.keys(exports.types);
-    return (_a = [getRequestBody()])
-        .concat.apply(_a, getParameters()).filter(Boolean)
+    return (_a = [transformRequestBody()])
+        .concat.apply(_a, transformParameters()).filter(Boolean)
         .map(function (group) {
         // Since this library assumes that the schema has already been dereferenced, adding every component here that
         // **isn't** circular adds a ton of bloat so it'd be cool if `components` was just the remaining `$ref` pointers

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

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -14,6 +25,7 @@ function getResponseExamples(operation) {
     return Object.keys(operation.responses || {})
         .map(function (status) {
         var response = operation.responses[status];
+        var onlyHeaders = false;
         // If we have a $ref here that means that this was a circular ref so we should ignore it.
         if ((0, rmoas_types_1.isRef)(response)) {
             return false;
@@ -31,13 +43,15 @@ function getResponseExamples(operation) {
                 mediaTypes[mediaType] = examples;
             }
         });
+        // If the response has no content, but has headers, hardcode an empty example so the headers modal will still display
+        if (response.headers && Object.keys(response.headers).length && !Object.keys(mediaTypes).length) {
+            mediaTypes['*/*'] = [];
+            onlyHeaders = true;
+        }
         if (!Object.keys(mediaTypes).length) {
             return false;
         }
-        return {
-            status: status,
-            mediaTypes: mediaTypes
-        };
+        return __assign({ status: status, mediaTypes: mediaTypes }, (onlyHeaders ? { onlyHeaders: onlyHeaders } : {}));
     })
         .filter(Boolean);
 }

package/dist/operation.js

@@ -39,6 +39,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 exports.__esModule = true;
 exports.Webhook = exports.Callback = void 0;
 var RMOAS = __importStar(require("./rmoas.types"));
+var dedupe_common_parameters_1 = __importDefault(require("./lib/dedupe-common-parameters"));
 var find_schema_definition_1 = __importDefault(require("./lib/find-schema-definition"));
 var get_parameters_as_json_schema_1 = __importDefault(require("./operation/get-parameters-as-json-schema"));
 var get_response_as_json_schema_1 = __importDefault(require("./operation/get-response-as-json-schema"));
@@ -333,13 +334,25 @@ var Operation = /** @class */ (function () {
     Operation.prototype.isDeprecated = function () {
         return 'deprecated' in this.schema ? this.schema.deprecated : false;
     };
+    /**
+     * Determine if the operation has any (non-request body) parameters.
+     *
+     */
+    Operation.prototype.hasParameters = function () {
+        return !!this.getParameters().length;
+    };
     /**
      * Return the parameters (non-request body) on the operation.
      *
-     * @todo This should also pull in common params.
      */
     Operation.prototype.getParameters = function () {
-        return ('parameters' in this.schema ? this.schema.parameters : []);
+        var _a, _b, _c, _d;
+        var parameters = (((_a = this.schema) === null || _a === void 0 ? void 0 : _a.parameters) || []);
+        var commonParams = (((_d = (_c = (_b = this.api) === null || _b === void 0 ? void 0 : _b.paths) === null || _c === void 0 ? void 0 : _c[this.path]) === null || _d === void 0 ? void 0 : _d.parameters) || []);
+        if (commonParams.length) {
+            parameters = parameters.concat((0, dedupe_common_parameters_1["default"])(parameters, commonParams) || []);
+        }
+        return parameters;
     };
     /**
      * Convert the operation into an array of JSON Schema schemas for each available type of parameter available on the
@@ -348,7 +361,7 @@ var Operation = /** @class */ (function () {
      * @param globalDefaults Contains an object of user defined schema defaults.
      */
     Operation.prototype.getParametersAsJsonSchema = function (globalDefaults) {
-        return (0, get_parameters_as_json_schema_1["default"])(this.path, this.schema, this.api, globalDefaults);
+        return (0, get_parameters_as_json_schema_1["default"])(this, this.api, globalDefaults);
     };
     /**
      * Get a single response for this status code, formatted as JSON schema.
@@ -372,9 +385,31 @@ var Operation = /** @class */ (function () {
     Operation.prototype.hasRequestBody = function () {
         return !!this.schema.requestBody;
     };
+    /**
+     * Retrieve the list of all available media types that the operations request body can accept.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
+     */
+    Operation.prototype.getRequestBodyMediaTypes = function () {
+        if (!this.hasRequestBody()) {
+            return [];
+        }
+        var requestBody = this.schema.requestBody;
+        if (RMOAS.isRef(requestBody)) {
+            // If the request body is still a `$ref` pointer we should return false because this library assumes that you've
+            // run dereferencing beforehand.
+            return [];
+        }
+        return Object.keys(requestBody.content);
+    };
     /**
      * Retrieve a specific request body content schema off this operation.
      *
+     * If no media type is supplied this will return either the first available JSON-like request body, or the first
+     * available if there are no JSON-like media types present. When this return comes back it's in the form of an array
+     * with the first key being the selected media type, followed by the media type object in question.
+     *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
      * @param mediaType Specific request body media type to retrieve if present.
@@ -384,12 +419,37 @@ var Operation = /** @class */ (function () {
             return false;
         }
         var requestBody = this.schema.requestBody;
-        if (RMOAS.isRef(requestBody) || !(mediaType in requestBody.content)) {
+        if (RMOAS.isRef(requestBody)) {
             // If the request body is still a `$ref` pointer we should return false because this library assumes that you've
             // run dereferencing beforehand.
             return false;
         }
-        return requestBody.content[mediaType];
+        if (mediaType) {
+            if (!(mediaType in requestBody.content)) {
+                return false;
+            }
+            return requestBody.content[mediaType];
+        }
+        // Since no media type was supplied we need to find either the first JSON-like media type that we've got, or the
+        // first available of anything else if no JSON-like media types are present.
+        var availableMediaType;
+        var mediaTypes = this.getRequestBodyMediaTypes();
+        mediaTypes.forEach(function (mt) {
+            if (!availableMediaType && matches_mimetype_1["default"].json(mt)) {
+                availableMediaType = mt;
+            }
+        });
+        if (!availableMediaType) {
+            mediaTypes.forEach(function (mt) {
+                if (!availableMediaType) {
+                    availableMediaType = mt;
+                }
+            });
+        }
+        if (availableMediaType) {
+            return [availableMediaType, requestBody.content[availableMediaType]];
+        }
+        return false;
     };
     /**
      * Retrieve an array of request body examples that this operation has.
@@ -552,6 +612,15 @@ var Callback = /** @class */ (function (_super) {
         }
         return ((_a = this.schema) === null || _a === void 0 ? void 0 : _a.description) ? this.schema.description.trim() : undefined;
     };
+    Callback.prototype.getParameters = function () {
+        var _a;
+        var parameters = (((_a = this.schema) === null || _a === void 0 ? void 0 : _a.parameters) || []);
+        var commonParams = (this.parentSchema.parameters || []);
+        if (commonParams.length) {
+            parameters = parameters.concat((0, dedupe_common_parameters_1["default"])(parameters, commonParams) || []);
+        }
+        return parameters;
+    };
     return Callback;
 }(Operation));
 exports.Callback = Callback;

package/dist/samples/index.js

@@ -6,20 +6,25 @@ exports.__esModule = true;
 var utils_1 = require("./utils");
 var memoizee_1 = __importDefault(require("memoizee"));
 var json_schema_merge_allof_1 = __importDefault(require("json-schema-merge-allof"));
+var sampleDefaults = function (genericSample) {
+    return function (schema) {
+        return typeof schema["default"] === typeof genericSample ? schema["default"] : genericSample;
+    };
+};
 var primitives = {
-    string: function () { return 'string'; },
-    string_email: function () { return 'user@example.com'; },
-    'string_date-time': function () { return new Date().toISOString(); },
-    string_date: function () { return new Date().toISOString().substring(0, 10); },
-    'string_YYYY-MM-DD': function () { return new Date().toISOString().substring(0, 10); },
-    string_uuid: function () { return '3fa85f64-5717-4562-b3fc-2c963f66afa6'; },
-    string_hostname: function () { return 'example.com'; },
-    string_ipv4: function () { return '198.51.100.42'; },
-    string_ipv6: function () { return '2001:0db8:5b96:0000:0000:426f:8e17:642a'; },
-    number: function () { return 0; },
-    number_float: function () { return 0.0; },
-    integer: function () { return 0; },
-    boolean: function (schema) { return (typeof schema["default"] === 'boolean' ? schema["default"] : true); }
+    string: sampleDefaults('string'),
+    string_email: sampleDefaults('user@example.com'),
+    'string_date-time': sampleDefaults(new Date().toISOString()),
+    string_date: sampleDefaults(new Date().toISOString().substring(0, 10)),
+    'string_YYYY-MM-DD': sampleDefaults(new Date().toISOString().substring(0, 10)),
+    string_uuid: sampleDefaults('3fa85f64-5717-4562-b3fc-2c963f66afa6'),
+    string_hostname: sampleDefaults('example.com'),
+    string_ipv4: sampleDefaults('198.51.100.42'),
+    string_ipv6: sampleDefaults('2001:0db8:5b96:0000:0000:426f:8e17:642a'),
+    number: sampleDefaults(0),
+    number_float: sampleDefaults(0.0),
+    integer: sampleDefaults(0),
+    boolean: sampleDefaults(true)
 };
 var primitive = function (schema) {
     schema = (0, utils_1.objectify)(schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "17.5.0",
+  "version": "17.7.2",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -59,7 +59,7 @@
     "jsonpointer": "^5.0.0",
     "memoizee": "^0.4.14",
     "minimist": "^1.2.0",
-    "oas-normalize": "^5.1.0",
+    "oas-normalize": "^5.1.1",
     "openapi-types": "^10.0.0",
     "path-to-regexp": "^6.2.0",
     "swagger-inline": "^5.0.2"

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

@@ -0,0 +1,25 @@
+import * as RMOAS from '../rmoas.types';
+
+/**
+ * With an array of common parameters filter down them to what isn't already present in a list of non-common
+ * parameters.
+ *
+ * @param parameters
+ * @param commonParameters
+ */
+export default function dedupeCommonParameters(
+  parameters: RMOAS.ParameterObject[],
+  commonParameters: RMOAS.ParameterObject[]
+) {
+  return commonParameters.filter((param: RMOAS.ParameterObject) => {
+    return !parameters.find((param2: RMOAS.ParameterObject) => {
+      if (param.name && param2.name) {
+        return param.name === param2.name && param.in === param2.in;
+      } else if (RMOAS.isRef(param) && RMOAS.isRef(param2)) {
+        return param.$ref === param2.$ref;
+      }
+
+      return false;
+    });
+  });
+}

package/src/lib/get-schema.ts

@@ -8,6 +8,7 @@ import findSchemaDefinition from './find-schema-definition';
  *
  * 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.

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

@@ -150,21 +150,12 @@ function searchForExampleByPointer(pointer: string, examples: PrevSchemasType =
       if ('example' in schema) {
         schema = schema.example;
       } else {
-        const keys = Object.keys(schema.examples);
-        if (!keys.length) {
+        if (!Array.isArray(schema.examples) || !schema.examples.length) {
           continue;
         }
 
         // Prevent us from crashing if `examples` is a completely empty object.
-        const ex = schema.examples[keys.shift() as unknown as number];
-
-        if (typeof ex !== 'object' || Array.isArray(ex)) {
-          continue;
-        } else if (!('value' in ex)) {
-          continue;
-        }
-
-        schema = ex.value;
+        schema = schema.examples.shift();
       }
 
       try {
@@ -376,7 +367,11 @@ export default function toJSONSchema(
               examples.push(example.value[0]);
               reshapedExamples = true;
             } else {
-              prevSchemas.push({ examples: schema.examples });
+              // If this example is neither a primitive or an array we should dump it into the `prevSchemas` array
+              // because we might be able to extract an example from it further downstream.
+              prevSchemas.push({
+                example: example.value,
+              });
             }
           }
         });

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

@@ -1,6 +1,6 @@
-import type { ComponentsObject, OASDocument, OperationObject, SchemaObject } from '../rmoas.types';
+import type { ComponentsObject, OASDocument, SchemaObject } from '../rmoas.types';
 import type { OpenAPIV3_1 } from 'openapi-types';
-import getSchema from '../lib/get-schema';
+import type Operation from '../operation';
 import matchesMimetype from '../lib/matches-mimetype';
 import toJSONSchema from '../lib/openapi-to-json-schema';
 import * as RMOAS from '../rmoas.types';
@@ -57,17 +57,11 @@ function cloneObject<T>(obj: T): T {
 }
 
 /**
- * @param path
  * @param operation
  * @param api
  * @param globalDefaults
  */
-export default function getParametersAsJsonSchema(
-  path: string,
-  operation: OperationObject,
-  api: OASDocument,
-  globalDefaults = {}
-) {
+export default function getParametersAsJsonSchema(operation: Operation, api: OASDocument, globalDefaults = {}) {
   let hasCircularRefs = false;
 
   function refLogger() {
@@ -122,32 +116,36 @@ export default function getParametersAsJsonSchema(
   /**
    *
    */
-  function getRequestBody(): SchemaWrapper {
-    const schema = getSchema(operation, api);
-    if (!schema || !schema.schema) return null;
+  function transformRequestBody(): SchemaWrapper {
+    const requestBody = operation.getRequestBody();
+    if (!requestBody || !Array.isArray(requestBody)) return null;
 
-    const type = schema.type === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
-    const requestBody = schema.schema;
+    const [mediaType, mediaTypeObject] = requestBody;
+    const type = mediaType === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
 
     // If this schema is completely empty, don't bother processing it.
-    if (Object.keys(requestBody.schema).length === 0) {
+    if (!Object.keys(mediaTypeObject.schema).length) {
       return null;
     }
 
-    const examples = [];
-    if ('example' in requestBody) {
-      examples.push({ example: requestBody.example });
-    } else if ('examples' in requestBody) {
-      examples.push({ examples: requestBody.examples });
+    const prevSchemas = [] as Array<RMOAS.SchemaObject>;
+    if ('example' in mediaTypeObject) {
+      prevSchemas.push({ example: mediaTypeObject.example });
+    } else if ('examples' in mediaTypeObject) {
+      prevSchemas.push({
+        examples: Object.values(mediaTypeObject.examples)
+          .map((example: RMOAS.ExampleObject) => example.value)
+          .filter(val => val !== undefined),
+      });
     }
 
     // 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(requestBody.schema);
-    const cleanedSchema = toJSONSchema(requestSchema, { globalDefaults, prevSchemas: examples, refLogger });
+    const requestSchema = cloneObject(mediaTypeObject.schema);
+    const cleanedSchema = toJSONSchema(requestSchema, { globalDefaults, prevSchemas, refLogger });
 
     // If this schema is **still** empty, don't bother returning it.
-    if (Object.keys(cleanedSchema).length === 0) {
+    if (!Object.keys(cleanedSchema).length) {
       return null;
     }
 
@@ -162,15 +160,7 @@ export default function getParametersAsJsonSchema(
     };
   }
 
-  function getCommonParams() {
-    if (api && 'paths' in api && path in api.paths && 'parameters' in api.paths[path]) {
-      return api.paths[path].parameters;
-    }
-
-    return [];
-  }
-
-  function getComponents(): ComponentsObject {
+  function transformComponents(): ComponentsObject {
     if (!('components' in api)) {
       return false;
     }
@@ -196,25 +186,8 @@ export default function getParametersAsJsonSchema(
     return components;
   }
 
-  function getParameters(): Array<SchemaWrapper> {
-    let operationParams = operation.parameters || [];
-    const commonParams = getCommonParams();
-
-    if (commonParams.length !== 0) {
-      const commonParamsNotInParams = commonParams.filter((param: RMOAS.ParameterObject) => {
-        return !operationParams.find((param2: RMOAS.ParameterObject) => {
-          if (param.name && param2.name) {
-            return param.name === param2.name && param.in === param2.in;
-          } else if (RMOAS.isRef(param) && RMOAS.isRef(param2)) {
-            return param.$ref === param2.$ref;
-          }
-
-          return false;
-        });
-      });
-
-      operationParams = operationParams.concat(commonParamsNotInParams || []);
-    }
+  function transformParameters(): Array<SchemaWrapper> {
+    const operationParams = operation.getParameters();
 
     return Object.keys(types).map(type => {
       const required: Array<string> = [];
@@ -330,15 +303,17 @@ export default function getParametersAsJsonSchema(
     });
   }
 
-  const hasRequestBody = !!operation.requestBody;
-  const hasParameters = !!(operation.parameters && operation.parameters.length !== 0);
-  if (!hasParameters && !hasRequestBody && getCommonParams().length === 0) return 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.
+  if (!operation.hasParameters() && !operation.hasRequestBody()) {
+    return null;
+  }
 
-  const components = getComponents();
+  const components = transformComponents();
 
   const typeKeys = Object.keys(types);
-  return [getRequestBody()]
-    .concat(...getParameters())
+  return [transformRequestBody()]
+    .concat(...transformParameters())
     .filter(Boolean)
     .map(group => {
       // Since this library assumes that the schema has already been dereferenced, adding every component here that

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

@@ -18,6 +18,7 @@ export default function getResponseExamples(operation: RMOAS.OperationObject) {
   return Object.keys(operation.responses || {})
     .map(status => {
       const response = operation.responses[status];
+      let onlyHeaders = false;
 
       // If we have a $ref here that means that this was a circular ref so we should ignore it.
       if (isRef(response)) {
@@ -39,6 +40,12 @@ export default function getResponseExamples(operation: RMOAS.OperationObject) {
         }
       });
 
+      // If the response has no content, but has headers, hardcode an empty example so the headers modal will still display
+      if (response.headers && Object.keys(response.headers).length && !Object.keys(mediaTypes).length) {
+        mediaTypes['*/*'] = [];
+        onlyHeaders = true;
+      }
+
       if (!Object.keys(mediaTypes).length) {
         return false;
       }
@@ -46,6 +53,7 @@ export default function getResponseExamples(operation: RMOAS.OperationObject) {
       return {
         status,
         mediaTypes,
+        ...(onlyHeaders ? { onlyHeaders } : {}),
       };
     })
     .filter(Boolean) as ResponseExamples;

package/src/operation.ts

@@ -4,6 +4,7 @@ import type { CallbackExamples } from './operation/get-callback-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
 
 import * as RMOAS from './rmoas.types';
+import dedupeCommonParameters from './lib/dedupe-common-parameters';
 import findSchemaDefinition from './lib/find-schema-definition';
 import getParametersAsJsonSchema from './operation/get-parameters-as-json-schema';
 import getResponseAsJsonSchema from './operation/get-response-as-json-schema';
@@ -382,13 +383,26 @@ export default class Operation {
     return 'deprecated' in this.schema ? this.schema.deprecated : false;
   }
 
+  /**
+   * Determine if the operation has any (non-request body) parameters.
+   *
+   */
+  hasParameters() {
+    return !!this.getParameters().length;
+  }
+
   /**
    * Return the parameters (non-request body) on the operation.
    *
-   * @todo This should also pull in common params.
    */
   getParameters(): Array<RMOAS.ParameterObject> {
-    return ('parameters' in this.schema ? this.schema.parameters : []) as Array<RMOAS.ParameterObject>;
+    let parameters = (this.schema?.parameters || []) as Array<RMOAS.ParameterObject>;
+    const commonParams = (this.api?.paths?.[this.path]?.parameters || []) as Array<RMOAS.ParameterObject>;
+    if (commonParams.length) {
+      parameters = parameters.concat(dedupeCommonParameters(parameters, commonParams) || []);
+    }
+
+    return parameters;
   }
 
   /**
@@ -398,7 +412,7 @@ export default class Operation {
    * @param globalDefaults Contains an object of user defined schema defaults.
    */
   getParametersAsJsonSchema(globalDefaults?: Record<string, unknown>) {
-    return getParametersAsJsonSchema(this.path, this.schema, this.api, globalDefaults);
+    return getParametersAsJsonSchema(this, this.api, globalDefaults);
   }
 
   /**
@@ -426,26 +440,81 @@ export default class Operation {
     return !!this.schema.requestBody;
   }
 
+  /**
+   * Retrieve the list of all available media types that the operations request body can accept.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
+   */
+  getRequestBodyMediaTypes() {
+    if (!this.hasRequestBody()) {
+      return [];
+    }
+
+    const requestBody = this.schema.requestBody;
+    if (RMOAS.isRef(requestBody)) {
+      // If the request body is still a `$ref` pointer we should return false because this library assumes that you've
+      // run dereferencing beforehand.
+      return [];
+    }
+
+    return Object.keys(requestBody.content);
+  }
+
   /**
    * Retrieve a specific request body content schema off this operation.
    *
+   * If no media type is supplied this will return either the first available JSON-like request body, or the first
+   * available if there are no JSON-like media types present. When this return comes back it's in the form of an array
+   * with the first key being the selected media type, followed by the media type object in question.
+   *
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}
    * @param mediaType Specific request body media type to retrieve if present.
    */
-  getRequestBody(mediaType: string) {
+  getRequestBody(mediaType?: string): false | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject] {
     if (!this.hasRequestBody()) {
       return false;
     }
 
     const requestBody = this.schema.requestBody;
-    if (RMOAS.isRef(requestBody) || !(mediaType in requestBody.content)) {
+    if (RMOAS.isRef(requestBody)) {
       // If the request body is still a `$ref` pointer we should return false because this library assumes that you've
       // run dereferencing beforehand.
       return false;
     }
 
-    return requestBody.content[mediaType];
+    if (mediaType) {
+      if (!(mediaType in requestBody.content)) {
+        return false;
+      }
+
+      return requestBody.content[mediaType];
+    }
+
+    // Since no media type was supplied we need to find either the first JSON-like media type that we've got, or the
+    // first available of anything else if no JSON-like media types are present.
+    let availableMediaType: string;
+    const mediaTypes = this.getRequestBodyMediaTypes();
+    mediaTypes.forEach((mt: string) => {
+      if (!availableMediaType && matchesMimeType.json(mt)) {
+        availableMediaType = mt;
+      }
+    });
+
+    if (!availableMediaType) {
+      mediaTypes.forEach((mt: string) => {
+        if (!availableMediaType) {
+          availableMediaType = mt;
+        }
+      });
+    }
+
+    if (availableMediaType) {
+      return [availableMediaType, requestBody.content[availableMediaType]];
+    }
+
+    return false;
   }
 
   /**
@@ -645,6 +714,16 @@ export class Callback extends Operation {
 
     return this.schema?.description ? this.schema.description.trim() : undefined;
   }
+
+  getParameters(): Array<RMOAS.ParameterObject> {
+    let parameters = (this.schema?.parameters || []) as Array<RMOAS.ParameterObject>;
+    const commonParams = (this.parentSchema.parameters || []) as Array<RMOAS.ParameterObject>;
+    if (commonParams.length) {
+      parameters = parameters.concat(dedupeCommonParameters(parameters, commonParams) || []);
+    }
+
+    return parameters;
+  }
 }
 
 export class Webhook extends Operation {}

package/src/rmoas.types.ts

@@ -60,6 +60,15 @@ export type ServerVariableObject = OpenAPIV3.ServerVariableObject | OpenAPIV3_1.
 export type ServerVariablesObject = {
   [variable: string]: ServerVariableObject;
 };
+export type ServerVariable = Record<
+  string,
+  string | number | Array<{ default?: string | number }> | { default?: string | number } | Record<string, never>
+>;
+
+export type Servers = {
+  selected: number;
+  variables: ServerVariable;
+};
 
 /**
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject}

package/src/samples/index.ts

@@ -9,20 +9,25 @@ import { objectify, usesPolymorphism, isFunc, normalizeArray, deeplyStripKey } f
 import memoize from 'memoizee';
 import mergeAllOf from 'json-schema-merge-allof';
 
+const sampleDefaults = (genericSample: string | number | boolean) => {
+  return (schema: RMOAS.SchemaObject): typeof genericSample =>
+    typeof schema.default === typeof genericSample ? schema.default : genericSample;
+};
+
 const primitives: Record<string, (arg: void | RMOAS.SchemaObject) => string | number | boolean> = {
-  string: () => 'string',
-  string_email: () => 'user@example.com',
-  'string_date-time': () => new Date().toISOString(),
-  string_date: () => new Date().toISOString().substring(0, 10),
-  'string_YYYY-MM-DD': () => new Date().toISOString().substring(0, 10),
-  string_uuid: () => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
-  string_hostname: () => 'example.com',
-  string_ipv4: () => '198.51.100.42',
-  string_ipv6: () => '2001:0db8:5b96:0000:0000:426f:8e17:642a',
-  number: () => 0,
-  number_float: () => 0.0,
-  integer: () => 0,
-  boolean: (schema: RMOAS.SchemaObject): boolean => (typeof schema.default === 'boolean' ? schema.default : true),
+  string: sampleDefaults('string'),
+  string_email: sampleDefaults('user@example.com'),
+  'string_date-time': sampleDefaults(new Date().toISOString()),
+  string_date: sampleDefaults(new Date().toISOString().substring(0, 10)),
+  'string_YYYY-MM-DD': sampleDefaults(new Date().toISOString().substring(0, 10)),
+  string_uuid: sampleDefaults('3fa85f64-5717-4562-b3fc-2c963f66afa6'),
+  string_hostname: sampleDefaults('example.com'),
+  string_ipv4: sampleDefaults('198.51.100.42'),
+  string_ipv6: sampleDefaults('2001:0db8:5b96:0000:0000:426f:8e17:642a'),
+  number: sampleDefaults(0),
+  number_float: sampleDefaults(0.0),
+  integer: sampleDefaults(0),
+  boolean: sampleDefaults(true),
 };
 
 const primitive = (schema: RMOAS.SchemaObject) => {