oas 17.3.1 → 17.4.2

package/@types/operation.d.ts

@@ -44,6 +44,8 @@ export default class Operation {
         response: Array<string>;
     };
     constructor(api: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject);
+    getSummary(): string;
+    getDescription(): string;
     getContentType(): string;
     isFormUrlEncoded(): boolean;
     isMultipart(): boolean;
@@ -210,7 +212,11 @@ export declare class Callback extends Operation {
      * The identifier that this callback is set to.
      */
     identifier: string;
-    constructor(oas: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject, identifier: string);
+    /**
+     * The parent path item object that this Callback exists within.
+     */
+    parentSchema: RMOAS.PathItemObject;
+    constructor(oas: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject, identifier: string, parentPathItem: RMOAS.PathItemObject);
     /**
      * Return the primary identifier for this callback.
      *
@@ -219,6 +225,8 @@ export declare class Callback extends Operation {
      * @returns {string}
      */
     getIdentifier(): string;
+    getSummary(): string;
+    getDescription(): string;
 }
 export declare class Webhook extends Operation {
 }

package/@types/utils.d.ts

@@ -1,5 +1,6 @@
 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;
@@ -16,3 +17,4 @@ declare const _default: {
     };
 };
 export default _default;
+export { supportedMethods };

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## <small>17.4.2 (2022-01-05)</small>
+
+* fix: callbacks not having path-level data to retrieve common summaries (#575) ([c7d1144](https://github.com/readmeio/oas/commit/c7d1144)), closes [#575](https://github.com/readmeio/oas/issues/575)
+* test: adding test coverage for OpenAPI 3.1 `pathItems` components ([77b596e](https://github.com/readmeio/oas/commit/77b596e))
+
+
+
+## <small>17.4.1 (2022-01-03)</small>
+
+* chore(deps-dev): bump @commitlint/cli from 15.0.0 to 16.0.1 (#569) ([ca515a9](https://github.com/readmeio/oas/commit/ca515a9)), closes [#569](https://github.com/readmeio/oas/issues/569)
+* chore(deps-dev): bump @commitlint/config-conventional (#567) ([c4c6cc0](https://github.com/readmeio/oas/commit/c4c6cc0)), closes [#567](https://github.com/readmeio/oas/issues/567)
+* chore(deps-dev): bump @types/jest from 27.0.3 to 27.4.0 (#574) ([eb21296](https://github.com/readmeio/oas/commit/eb21296)), closes [#574](https://github.com/readmeio/oas/issues/574)
+* chore(deps-dev): bump eslint from 8.3.0 to 8.6.0 (#570) ([0dd19b1](https://github.com/readmeio/oas/commit/0dd19b1)), closes [#570](https://github.com/readmeio/oas/issues/570)
+* chore(deps-dev): bump eslint-plugin-jsdoc from 37.1.0 to 37.5.0 (#571) ([b21ebfe](https://github.com/readmeio/oas/commit/b21ebfe)), closes [#571](https://github.com/readmeio/oas/issues/571)
+* chore(deps-dev): bump jest from 27.4.3 to 27.4.5 (#573) ([4266065](https://github.com/readmeio/oas/commit/4266065)), closes [#573](https://github.com/readmeio/oas/issues/573)
+* chore(deps-dev): bump prettier from 2.5.0 to 2.5.1 (#568) ([b4548c0](https://github.com/readmeio/oas/commit/b4548c0)), closes [#568](https://github.com/readmeio/oas/issues/568)
+* chore(deps-dev): bump ts-jest from 27.0.7 to 27.1.2 (#566) ([16edcb0](https://github.com/readmeio/oas/commit/16edcb0)), closes [#566](https://github.com/readmeio/oas/issues/566)
+* chore(deps-dev): bump typescript from 4.5.2 to 4.5.4 (#565) ([7bafc0d](https://github.com/readmeio/oas/commit/7bafc0d)), closes [#565](https://github.com/readmeio/oas/issues/565)
+* chore(deps): bump actions/setup-node from 2.5.0 to 2.5.1 (#564) ([125afbe](https://github.com/readmeio/oas/commit/125afbe)), closes [#564](https://github.com/readmeio/oas/issues/564)
+* chore(deps): bump openapi-types from 9.3.1 to 10.0.0 (#572) ([43e681b](https://github.com/readmeio/oas/commit/43e681b)), closes [#572](https://github.com/readmeio/oas/issues/572)
+* chore(deps): upgrading oas-normalize ([851cf95](https://github.com/readmeio/oas/commit/851cf95))
+* fix: improved support for common params (#563) ([ae3cb83](https://github.com/readmeio/oas/commit/ae3cb83)), closes [#563](https://github.com/readmeio/oas/issues/563)
+
+
+
+## 17.4.0 (2021-12-17)
+
+* feat: adding accessors for operation summary and description (#562) ([1dd6a9f](https://github.com/readmeio/oas/commit/1dd6a9f)), closes [#562](https://github.com/readmeio/oas/issues/562)
+
+
+
+## <small>17.3.2 (2021-12-14)</small>
+
+* fix: exclude readonly params from deprecatedProps (#561) ([3342bf2](https://github.com/readmeio/oas/commit/3342bf2)), closes [#561](https://github.com/readmeio/oas/issues/561)
+* test: adding a regression case for the enum typescript quirk (#560) ([fabf01b](https://github.com/readmeio/oas/commit/fabf01b)), closes [#560](https://github.com/readmeio/oas/issues/560)
+
+
+
 ## <small>17.3.1 (2021-12-08)</small>
 
 * fix: upgrading oas-normalize to fix a rare npm installation issue (#558) ([ce6123d](https://github.com/readmeio/oas/commit/ce6123d)), closes [#558](https://github.com/readmeio/oas/issues/558)

package/dist/index.js

@@ -78,7 +78,7 @@ var operation_1 = __importStar(require("./operation"));
 exports.Operation = operation_1["default"];
 exports.Callback = operation_1.Callback;
 exports.Webhook = operation_1.Webhook;
-var utils_1 = __importDefault(require("./utils"));
+var utils_1 = __importStar(require("./utils"));
 exports.utils = utils_1["default"];
 /**
  * @param url URL to ensure that it has an HTTP protocol.
@@ -611,12 +611,11 @@ var Oas = /** @class */ (function () {
         // the paths object that isn't a known HTTP method.
         // https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-7
         // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-7
-        var supportedMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
         var paths = {};
         Object.keys(this.api.paths ? this.api.paths : []).forEach(function (path) {
             paths[path] = {};
             Object.keys(_this.api.paths[path]).forEach(function (method) {
-                if (!supportedMethods.has(method))
+                if (!utils_1.supportedMethods.has(method))
                     return;
                 paths[path][method] = _this.operation(path, method);
             });

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

@@ -107,11 +107,11 @@ exports["default"] = (function (path, operation, api, globalDefaults) {
         var deprecatedBody = cloneObject(schema);
         // Booleans are not valid for required in draft 4, 7 or 2020. Not sure why the typing thinks they are.
         var requiredParams = (schema.required || []);
-        // Find all top-level deprecated properties from the schema - required params are excluded
+        // Find all top-level deprecated properties from the schema - required and readOnly params are excluded
         var allDeprecatedProps = {};
         Object.keys(deprecatedBody.properties).forEach(function (key) {
             var deprecatedProp = deprecatedBody.properties[key];
-            if (deprecatedProp.deprecated && !requiredParams.includes(key)) {
+            if (deprecatedProp.deprecated && !requiredParams.includes(key) && !deprecatedProp.readOnly) {
                 allDeprecatedProps[key] = deprecatedProp;
             }
         });

package/dist/operation.js

@@ -46,6 +46,7 @@ var get_requestbody_examples_1 = __importDefault(require("./operation/get-reques
 var get_callback_examples_1 = __importDefault(require("./operation/get-callback-examples"));
 var get_response_examples_1 = __importDefault(require("./operation/get-response-examples"));
 var matches_mimetype_1 = __importDefault(require("./lib/matches-mimetype"));
+var utils_1 = require("./utils");
 var Operation = /** @class */ (function () {
     function Operation(api, path, method, operation) {
         this.schema = operation;
@@ -57,6 +58,20 @@ var Operation = /** @class */ (function () {
         this.responseExamples = undefined;
         this.callbackExamples = undefined;
     }
+    Operation.prototype.getSummary = function () {
+        var _a;
+        if (this.api.paths[this.path].summary) {
+            return this.api.paths[this.path].summary;
+        }
+        return ((_a = this.schema) === null || _a === void 0 ? void 0 : _a.summary) ? this.schema.summary.trim() : undefined;
+    };
+    Operation.prototype.getDescription = function () {
+        var _a;
+        if (this.api.paths[this.path].description) {
+            return this.api.paths[this.path].description;
+        }
+        return ((_a = this.schema) === null || _a === void 0 ? void 0 : _a.description) ? this.schema.description.trim() : undefined;
+    };
     Operation.prototype.getContentType = function () {
         var _this = this;
         if (this.contentType) {
@@ -434,7 +449,7 @@ var Operation = /** @class */ (function () {
             : false;
         if (!callback || !callback[method])
             return false;
-        return new Callback(this.api, expression, method, callback[method], identifier);
+        return new Callback(this.api, expression, method, callback[method], identifier, callback);
     };
     /**
      * Retrieve an array of operations created from each callback.
@@ -453,6 +468,8 @@ var Operation = /** @class */ (function () {
                     var exp = cb[expression];
                     if (!RMOAS.isRef(exp)) {
                         Object.keys(exp).forEach(function (method) {
+                            if (!utils_1.supportedMethods.has(method))
+                                return;
                             callbackOperations.push(_this.getCallback(callback, expression, method));
                         });
                     }
@@ -501,9 +518,10 @@ var Operation = /** @class */ (function () {
 exports["default"] = Operation;
 var Callback = /** @class */ (function (_super) {
     __extends(Callback, _super);
-    function Callback(oas, path, method, operation, identifier) {
+    function Callback(oas, path, method, operation, identifier, parentPathItem) {
         var _this = _super.call(this, oas, path, method, operation) || this;
         _this.identifier = identifier;
+        _this.parentSchema = parentPathItem;
         return _this;
     }
     /**
@@ -516,6 +534,20 @@ var Callback = /** @class */ (function (_super) {
     Callback.prototype.getIdentifier = function () {
         return this.identifier;
     };
+    Callback.prototype.getSummary = function () {
+        var _a;
+        if (this.parentSchema.summary) {
+            return this.parentSchema.summary;
+        }
+        return ((_a = this.schema) === null || _a === void 0 ? void 0 : _a.summary) ? this.schema.summary.trim() : undefined;
+    };
+    Callback.prototype.getDescription = function () {
+        var _a;
+        if (this.parentSchema.description) {
+            return this.parentSchema.description;
+        }
+        return ((_a = this.schema) === null || _a === void 0 ? void 0 : _a.description) ? this.schema.description.trim() : undefined;
+    };
     return Callback;
 }(Operation));
 exports.Callback = Callback;

package/dist/utils.js

@@ -3,10 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": 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"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "17.3.1",
+  "version": "17.4.2",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",
@@ -59,14 +59,14 @@
     "jsonpointer": "^5.0.0",
     "memoizee": "^0.4.14",
     "minimist": "^1.2.0",
-    "oas-normalize": "^5.0.5",
-    "openapi-types": "^9.3.0",
+    "oas-normalize": "^5.1.0",
+    "openapi-types": "^10.0.0",
     "path-to-regexp": "^6.2.0",
     "swagger-inline": "^5.0.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "^15.0.0",
-    "@commitlint/config-conventional": "^15.0.0",
+    "@commitlint/cli": "^16.0.1",
+    "@commitlint/config-conventional": "^16.0.0",
     "@readme/eslint-config": "^8.0.2",
     "@readme/oas-examples": "^4.3.2",
     "@types/jest": "^27.0.2",

package/src/index.ts

@@ -7,7 +7,7 @@ import { pathToRegexp, match } from 'path-to-regexp';
 import getAuth from './lib/get-auth';
 import getUserVariable from './lib/get-user-variable';
 import Operation, { Callback, Webhook } from './operation';
-import utils from './utils';
+import utils, { supportedMethods } from './utils';
 
 type PathMatch = {
   url: {
@@ -640,7 +640,6 @@ export default class Oas {
     // the paths object that isn't a known HTTP method.
     // https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-7
     // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-7
-    const supportedMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
     const paths: Record<string, Record<RMOAS.HttpMethods, Operation | Webhook>> = {};
 
     Object.keys(this.api.paths ? this.api.paths : []).forEach(path => {

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

@@ -89,12 +89,12 @@ export default (path: string, operation: OperationObject, api: OASDocument, glob
     // Booleans are not valid for required in draft 4, 7 or 2020. Not sure why the typing thinks they are.
     const requiredParams = (schema.required || []) as Array<string>;
 
-    // Find all top-level deprecated properties from the schema - required params are excluded
+    // Find all top-level deprecated properties from the schema - required and readOnly params are excluded
     const allDeprecatedProps: { [key: string]: SchemaObject } = {};
 
     Object.keys(deprecatedBody.properties).forEach(key => {
       const deprecatedProp = deprecatedBody.properties[key] as SchemaObject;
-      if (deprecatedProp.deprecated && !requiredParams.includes(key)) {
+      if (deprecatedProp.deprecated && !requiredParams.includes(key) && !deprecatedProp.readOnly) {
         allDeprecatedProps[key] = deprecatedProp;
       }
     });

package/src/operation.ts

@@ -11,6 +11,7 @@ import getRequestBodyExamples from './operation/get-requestbody-examples';
 import getCallbackExamples from './operation/get-callback-examples';
 import getResponseExamples from './operation/get-response-examples';
 import matchesMimeType from './lib/matches-mimetype';
+import { supportedMethods } from './utils';
 
 type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
 
@@ -75,6 +76,22 @@ export default class Operation {
     this.callbackExamples = undefined;
   }
 
+  getSummary(): string {
+    if (this.api.paths[this.path].summary) {
+      return this.api.paths[this.path].summary;
+    }
+
+    return this.schema?.summary ? this.schema.summary.trim() : undefined;
+  }
+
+  getDescription(): string {
+    if (this.api.paths[this.path].description) {
+      return this.api.paths[this.path].description;
+    }
+
+    return this.schema?.description ? this.schema.description.trim() : undefined;
+  }
+
   getContentType(): string {
     if (this.contentType) {
       return this.contentType;
@@ -498,7 +515,7 @@ export default class Operation {
       : false;
 
     if (!callback || !callback[method]) return false;
-    return new Callback(this.api, expression, method, callback[method], identifier);
+    return new Callback(this.api, expression, method, callback[method], identifier, callback);
   }
 
   /**
@@ -519,6 +536,8 @@ export default class Operation {
 
           if (!RMOAS.isRef(exp)) {
             Object.keys(exp).forEach((method: RMOAS.HttpMethods) => {
+              if (!supportedMethods.has(method)) return;
+
               callbackOperations.push(this.getCallback(callback, expression, method));
             });
           }
@@ -574,16 +593,23 @@ export class Callback extends Operation {
    */
   identifier: string;
 
+  /**
+   * The parent path item object that this Callback exists within.
+   */
+  parentSchema: RMOAS.PathItemObject;
+
   constructor(
     oas: RMOAS.OASDocument,
     path: string,
     method: RMOAS.HttpMethods,
     operation: RMOAS.OperationObject,
-    identifier: string
+    identifier: string,
+    parentPathItem: RMOAS.PathItemObject
   ) {
     super(oas, path, method, operation);
 
     this.identifier = identifier;
+    this.parentSchema = parentPathItem;
   }
 
   /**
@@ -596,6 +622,22 @@ export class Callback extends Operation {
   getIdentifier(): string {
     return this.identifier;
   }
+
+  getSummary(): string {
+    if (this.parentSchema.summary) {
+      return this.parentSchema.summary;
+    }
+
+    return this.schema?.summary ? this.schema.summary.trim() : undefined;
+  }
+
+  getDescription(): string {
+    if (this.parentSchema.description) {
+      return this.parentSchema.description;
+    }
+
+    return this.schema?.description ? this.schema.description.trim() : undefined;
+  }
 }
 
 export class Webhook extends Operation {}

package/src/utils.ts

@@ -3,9 +3,13 @@ import getSchema from './lib/get-schema';
 import matchesMimeType from './lib/matches-mimetype';
 import { types as jsonSchemaTypes } from './operation/get-parameters-as-json-schema';
 
+const supportedMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+
 export default {
   findSchemaDefinition,
   getSchema,
   jsonSchemaTypes,
   matchesMimeType,
 };
+
+export { supportedMethods };