oas 20.3.0 → 20.5.0

package/.vscode/settings.json

@@ -1,3 +1,5 @@
 {
-  "js/ts.implicitProjectConfig.strictNullChecks": false
+  "editor.codeActionsOnSave": {
+    "source.fixAll": true
+  }
 }

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 20.5.0 (2023-03-02)
+
+* chore: bumping out of date deps ([a905664](https://github.com/readmeio/oas/commit/a905664))
+* chore(deps): bumping deps ([f0de8b9](https://github.com/readmeio/oas/commit/f0de8b9))
+* fix: only adding components to generated JSON Schema if we need to (#732) ([9787b4d](https://github.com/readmeio/oas/commit/9787b4d)), closes [#732](https://github.com/readmeio/oas/issues/732)
+
+
+
+## 20.4.0 (2023-01-12)
+
+* feat: pass through requestBody descriptions (#730) ([3272137](https://github.com/readmeio/oas/commit/3272137)), closes [#730](https://github.com/readmeio/oas/issues/730)
+
+
+
 ## 20.3.0 (2023-01-03)
 
 * chore: bumping deps ([ed5e473](https://github.com/readmeio/oas/commit/ed5e473))

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

@@ -5,6 +5,7 @@ export interface SchemaWrapper {
     type: string;
     label?: string;
     schema: SchemaObject;
+    description?: string;
     deprecatedProps?: SchemaWrapper;
 }
 /**

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

@@ -127,7 +127,7 @@ function getParametersAsJSONSchema(operation, api, opts) {
         var requestBody = operation.getRequestBody();
         if (!requestBody || !Array.isArray(requestBody))
             return null;
-        var mediaType = requestBody[0], mediaTypeObject = requestBody[1];
+        var mediaType = requestBody[0], mediaTypeObject = requestBody[1], description = requestBody[2];
         var type = mediaType === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
         // If this schema is completely empty, don't bother processing it.
         if (!mediaTypeObject.schema || !Object.keys(mediaTypeObject.schema).length) {
@@ -157,30 +157,38 @@ function getParametersAsJSONSchema(operation, api, opts) {
         if (!Object.keys(cleanedSchema).length) {
             return null;
         }
-        return {
-            type: type,
-            label: exports.types[type],
-            schema: (0, openapi_to_json_schema_1.isPrimitive)(cleanedSchema)
+        return __assign({ type: type, label: exports.types[type], schema: (0, openapi_to_json_schema_1.isPrimitive)(cleanedSchema)
                 ? cleanedSchema
-                : __assign(__assign({}, cleanedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(cleanedSchema, api) }),
-            deprecatedProps: getDeprecated(cleanedSchema, type)
-        };
+                : __assign(__assign({}, cleanedSchema), { $schema: (0, openapi_to_json_schema_1.getSchemaVersionString)(cleanedSchema, api) }), deprecatedProps: getDeprecated(cleanedSchema, type) }, (description ? { description: description } : {}));
     }
     function transformComponents() {
         if (!('components' in api)) {
             return false;
         }
-        var components = {};
+        var components = {
+            /**
+             * Initializing an empty `components[componentType] = {}` object within the `forEach` below
+             * is incredibly slow because each of these component types has a wide variety of shapes. So
+             * in order to not have TS compilation times that takes literally **seconds** because of a
+             * single line we're instead opting to prefill this object with some empty placeholders that
+             * we'll later remove if they didn't get used.
+             *
+             * Obviously not ideal but I'd rather have a couple lines of boilerplate nonsense than having
+             * to wait a noticeably frustrating amount of time for TS Intellisense to reload itself after
+             * you save a line in any file.
+             */
+            examples: {},
+            schemas: {},
+            responses: {},
+            parameters: {},
+            requestBodies: {},
+            headers: {},
+            securitySchemes: {},
+            links: {},
+            callbacks: {}
+        };
         Object.keys(api.components).forEach(function (componentType) {
             if (typeof api.components[componentType] === 'object' && !Array.isArray(api.components[componentType])) {
-                /**
-                 * Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large
-                 * variety of types that that object could represent but I can't yet think of a way to get
-                 * around that.
-                 *
-                 * @todo
-                 */
-                components[componentType] = {};
                 Object.keys(api.components[componentType]).forEach(function (schemaName) {
                     var componentSchema = (0, clone_object_1["default"])(api.components[componentType][schemaName]);
                     components[componentType][schemaName] = (0, openapi_to_json_schema_1["default"])(componentSchema, {
@@ -191,6 +199,22 @@ function getParametersAsJSONSchema(operation, api, opts) {
                 });
             }
         });
+        // If none of our above component type placeholders got used let's clean them up.
+        [
+            'examples',
+            'schemas',
+            'responses',
+            'parameters',
+            'requestBodies',
+            'headers',
+            'securitySchemes',
+            'links',
+            'callbacks',
+        ].forEach(function (componentType) {
+            if (!Object.keys(components[componentType]).length) {
+                delete components[componentType];
+            }
+        });
         return components;
     }
     function transformParameters() {
@@ -345,10 +369,14 @@ function getParametersAsJSONSchema(operation, api, opts) {
     if (!operation.hasParameters() && !operation.hasRequestBody()) {
         return null;
     }
-    var components = transformComponents();
     var typeKeys = Object.keys(exports.types);
-    return (_a = [transformRequestBody()])
-        .concat.apply(_a, transformParameters()).filter(Boolean)
+    var jsonSchema = (_a = [transformRequestBody()]).concat.apply(_a, transformParameters()).filter(Boolean);
+    // We should only include `components`, or even bother transforming components into JSON Schema,
+    // if we either have circular refs or if we have discriminator mapping refs somewhere and want to
+    // include them.
+    var shouldIncludeComponents = hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs);
+    var components = shouldIncludeComponents ? transformComponents() : false;
+    return jsonSchema
         .map(function (group) {
         /**
          * Since this library assumes that the schema has already been dereferenced, adding every
@@ -357,13 +385,9 @@ function getParametersAsJSONSchema(operation, api, opts) {
          *
          * @todo
          */
-        if (components) {
-            // We should only include components if we've got circular refs or we have discriminator
-            // mapping refs (we want to include them).
-            if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
-                // Fixing typing and confused version mismatches
-                group.schema.components = components;
-            }
+        if (components && shouldIncludeComponents) {
+            // Fixing typing and confused version mismatches
+            group.schema.components = components;
         }
         // Delete deprecatedProps if it's null on the schema.
         if (!group.deprecatedProps)

package/dist/operation.d.ts

@@ -210,7 +210,7 @@ export default class Operation {
      * @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 | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject];
+    getRequestBody(mediaType?: string): false | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject, ...string[]];
     /**
      * Retrieve an array of request body examples that this operation has.
      *

package/dist/operation.js

@@ -48,6 +48,15 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -543,7 +552,10 @@ var Operation = /** @class */ (function () {
             });
         }
         if (availableMediaType) {
-            return [availableMediaType, requestBody.content[availableMediaType]];
+            return __spreadArray([
+                availableMediaType,
+                requestBody.content[availableMediaType]
+            ], (requestBody.description ? [requestBody.description] : []), true);
         }
         return false;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "20.3.0",
+  "version": "20.5.0",
   "description": "Comprehensive tooling for working with OpenAPI definitions",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -52,26 +52,26 @@
     "jsonpath-plus": "^7.2.0",
     "jsonpointer": "^5.0.0",
     "memoizee": "^0.4.14",
-    "oas-normalize": "^8.3.0",
+    "oas-normalize": "^8.3.2",
     "openapi-types": "^12.1.0",
     "path-to-regexp": "^6.2.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.3.0",
-    "@commitlint/config-conventional": "^17.3.0",
-    "@readme/eslint-config": "^10.3.2",
+    "@commitlint/cli": "^17.4.4",
+    "@commitlint/config-conventional": "^17.4.4",
+    "@readme/eslint-config": "^10.5.1",
     "@readme/oas-examples": "^5.7.1",
     "@readme/openapi-parser": "^2.4.0",
-    "@types/jest": "^29.2.5",
+    "@types/jest": "^29.4.0",
     "@types/json-schema-merge-allof": "^0.6.1",
     "@types/memoizee": "^0.4.6",
-    "@types/node": "^18.11.18",
-    "eslint": "^8.31.0",
+    "@types/node": "^18.14.4",
+    "eslint": "^8.35.0",
     "husky": "^8.0.3",
-    "jest": "^29.3.1",
-    "prettier": "^2.8.1",
-    "ts-jest": "^29.0.3",
-    "typescript": "^4.9.4"
+    "jest": "^29.4.3",
+    "prettier": "^2.8.4",
+    "ts-jest": "^29.0.5",
+    "typescript": "^4.9.5"
   },
   "prettier": "@readme/eslint-config/prettier",
   "commitlint": {

package/src/index.ts

@@ -110,7 +110,7 @@ function normalizePath(path: string) {
       // also handling quirks here like if there's an optional proceeding or trailing curly bracket
       // (`{{pathParam}` or `{pathParam}}`) as any unescaped curlys, which would be present in
       // `:pathParam}`, will throw a regex exception.
-      .replace(/({?){(.*?)}(}?)/g, function (str, ...args) {
+      .replace(/({?){(.*?)}(}?)/g, (str, ...args) => {
         // If a path contains a path parameter with hyphens, like `:dlc-release`, when it's regexd
         // with `path-to-regexp` it match against the `:dlc` portion of the parameter, breaking all
         // matching against the full path.

package/src/lib/matches-mimetype.ts

@@ -1,5 +1,5 @@
 function matchesMediaType(types: string[], mediaType: string): boolean {
-  return types.some(function (type) {
+  return types.some(type => {
     return mediaType.indexOf(type) > -1;
   });
 }

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

@@ -13,6 +13,7 @@ export interface SchemaWrapper {
   type: string;
   label?: string;
   schema: SchemaObject;
+  description?: string;
   deprecatedProps?: SchemaWrapper;
 }
 
@@ -124,7 +125,7 @@ export default function getParametersAsJSONSchema(
     const requestBody = operation.getRequestBody();
     if (!requestBody || !Array.isArray(requestBody)) return null;
 
-    const [mediaType, mediaTypeObject] = requestBody;
+    const [mediaType, mediaTypeObject, description] = requestBody;
     const type = mediaType === 'application/x-www-form-urlencoded' ? 'formData' : 'body';
 
     // If this schema is completely empty, don't bother processing it.
@@ -146,6 +147,7 @@ export default function getParametersAsJSONSchema(
     // We're cloning the request schema because we've had issues with request schemas that were
     // dereferenced being processed multiple times because their component is also processed.
     const requestSchema = cloneObject(mediaTypeObject.schema);
+
     const cleanedSchema = toJSONSchema(requestSchema, {
       globalDefaults: opts.globalDefaults,
       prevSchemas,
@@ -168,6 +170,7 @@ export default function getParametersAsJSONSchema(
             $schema: getSchemaVersionString(cleanedSchema, api),
           },
       deprecatedProps: getDeprecated(cleanedSchema, type),
+      ...(description ? { description } : {}),
     };
   }
 
@@ -176,19 +179,31 @@ export default function getParametersAsJSONSchema(
       return false;
     }
 
-    const components: Partial<ComponentsObject> = {};
+    const components: Partial<ComponentsObject> = {
+      /**
+       * Initializing an empty `components[componentType] = {}` object within the `forEach` below
+       * is incredibly slow because each of these component types has a wide variety of shapes. So
+       * in order to not have TS compilation times that takes literally **seconds** because of a
+       * single line we're instead opting to prefill this object with some empty placeholders that
+       * we'll later remove if they didn't get used.
+       *
+       * Obviously not ideal but I'd rather have a couple lines of boilerplate nonsense than having
+       * to wait a noticeably frustrating amount of time for TS Intellisense to reload itself after
+       * you save a line in any file.
+       */
+      examples: {},
+      schemas: {},
+      responses: {},
+      parameters: {},
+      requestBodies: {},
+      headers: {},
+      securitySchemes: {},
+      links: {},
+      callbacks: {},
+    };
 
     Object.keys(api.components).forEach((componentType: keyof ComponentsObject) => {
       if (typeof api.components[componentType] === 'object' && !Array.isArray(api.components[componentType])) {
-        /**
-         * Typescript is INCREDIBLY SLOW parsing this one line. I think it's because of the large
-         * variety of types that that object could represent but I can't yet think of a way to get
-         * around that.
-         *
-         * @todo
-         */
-        components[componentType] = {};
-
         Object.keys(api.components[componentType]).forEach(schemaName => {
           const componentSchema = cloneObject(api.components[componentType][schemaName]);
           components[componentType][schemaName] = toJSONSchema(componentSchema as SchemaObject, {
@@ -200,6 +215,23 @@ export default function getParametersAsJSONSchema(
       }
     });
 
+    // If none of our above component type placeholders got used let's clean them up.
+    [
+      'examples',
+      'schemas',
+      'responses',
+      'parameters',
+      'requestBodies',
+      'headers',
+      'securitySchemes',
+      'links',
+      'callbacks',
+    ].forEach((componentType: keyof ComponentsObject) => {
+      if (!Object.keys(components[componentType]).length) {
+        delete components[componentType];
+      }
+    });
+
     return components;
   }
 
@@ -375,12 +407,18 @@ export default function getParametersAsJSONSchema(
     return null;
   }
 
-  const components = transformComponents();
-
   const typeKeys = Object.keys(types);
-  return [transformRequestBody()]
-    .concat(...transformParameters())
-    .filter(Boolean)
+  const jsonSchema = [transformRequestBody()].concat(...transformParameters()).filter(Boolean);
+
+  // We should only include `components`, or even bother transforming components into JSON Schema,
+  // if we either have circular refs or if we have discriminator mapping refs somewhere and want to
+  // include them.
+  const shouldIncludeComponents =
+    hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs);
+
+  const components = shouldIncludeComponents ? transformComponents() : false;
+
+  return jsonSchema
     .map(group => {
       /**
        * Since this library assumes that the schema has already been dereferenced, adding every
@@ -389,13 +427,9 @@ export default function getParametersAsJSONSchema(
        *
        * @todo
        */
-      if (components) {
-        // We should only include components if we've got circular refs or we have discriminator
-        // mapping refs (we want to include them).
-        if (hasCircularRefs || (hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs)) {
-          // Fixing typing and confused version mismatches
-          (group.schema.components as ComponentsObject) = components;
-        }
+      if (components && shouldIncludeComponents) {
+        // Fixing typing and confused version mismatches
+        (group.schema.components as ComponentsObject) = components;
       }
 
       // Delete deprecatedProps if it's null on the schema.

package/src/operation.ts

@@ -621,7 +621,7 @@ export default class Operation {
    * @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 | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject] {
+  getRequestBody(mediaType?: string): false | RMOAS.MediaTypeObject | [string, RMOAS.MediaTypeObject, ...string[]] {
     if (!this.hasRequestBody()) {
       return false;
     }
@@ -660,7 +660,11 @@ export default class Operation {
     }
 
     if (availableMediaType) {
-      return [availableMediaType, requestBody.content[availableMediaType]];
+      return [
+        availableMediaType,
+        requestBody.content[availableMediaType],
+        ...(requestBody.description ? [requestBody.description] : []),
+      ];
     }
 
     return false;