oas 17.8.0 → 17.8.1

package/@types/operation.d.ts

@@ -1,6 +1,7 @@
 import type { RequestBodyExamples } from './operation/get-requestbody-examples';
 import type { CallbackExamples } from './operation/get-callback-examples';
 import type { ResponseExamples } from './operation/get-response-examples';
+import type { SchemaWrapper } from './operation/get-parameters-as-json-schema';
 import * as RMOAS from './rmoas.types';
 declare type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
 export default class Operation {
@@ -43,6 +44,10 @@ export default class Operation {
         request: string[];
         response: string[];
     };
+    /**
+     * All parameters and request bodies converted into JSON Schema.
+     */
+    parameterJsonSchema: SchemaWrapper[];
     constructor(api: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject);
     getSummary(): string;
     getDescription(): string;
@@ -84,11 +89,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 +118,18 @@ 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[];
+    getParametersAsJsonSchema(globalDefaults?: Record<string, unknown>): SchemaWrapper[];
     /**
      * Get a single response for this status code, formatted as JSON schema.
      *
@@ -144,6 +158,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/CHANGELOG.md

@@ -1,3 +1,11 @@
+## <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/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,6 +371,13 @@ 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.
@@ -365,7 +385,11 @@ 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, this.api, globalDefaults);
+        if (this.parameterJsonSchema) {
+            return this.parameterJsonSchema;
+        }
+        this.parameterJsonSchema = (0, get_parameters_as_json_schema_1["default"])(this, this.api, globalDefaults);
+        return this.parameterJsonSchema;
     };
     /**
      * Get a single response for this status code, formatted as JSON schema.
@@ -407,6 +431,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas",
-  "version": "17.8.0",
+  "version": "17.8.1",
   "description": "Working with OpenAPI definitions is hard. This makes it easier.",
   "license": "MIT",
   "author": "ReadMe <support@readme.io> (https://readme.com)",

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/operation.ts

@@ -2,6 +2,7 @@ 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';
+import type { SchemaWrapper } from './operation/get-parameters-as-json-schema';
 
 import * as RMOAS from './rmoas.types';
 import dedupeCommonParameters from './lib/dedupe-common-parameters';
@@ -65,6 +66,11 @@ export default class Operation {
     response: string[];
   };
 
+  /**
+   * All parameters and request bodies converted into JSON Schema.
+   */
+  parameterJsonSchema: SchemaWrapper[];
+
   constructor(api: RMOAS.OASDocument, path: string, method: RMOAS.HttpMethods, operation: RMOAS.OperationObject) {
     this.schema = operation;
     this.api = api;
@@ -323,22 +329,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,6 +427,14 @@ 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.
@@ -412,7 +442,12 @@ export default class Operation {
    * @param globalDefaults Contains an object of user defined schema defaults.
    */
   getParametersAsJsonSchema(globalDefaults?: Record<string, unknown>) {
-    return getParametersAsJsonSchema(this, this.api, globalDefaults);
+    if (this.parameterJsonSchema) {
+      return this.parameterJsonSchema;
+    }
+
+    this.parameterJsonSchema = getParametersAsJsonSchema(this, this.api, globalDefaults);
+    return this.parameterJsonSchema;
   }
 
   /**
@@ -461,6 +496,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.
    *