@kevinoid/openapi-transformers 0.1.0

package/read-only-not-required.js

@@ -0,0 +1,111 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/read-only-not-required.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to ensure readOnly schema properties are not required, to work
+ * around lack of support in generators.
+ *
+ * The behavior of required readOnly/writeOnly properties is defined in OAS3
+ * (the requirement only applies on response/request), but not in OAS2 (where
+ * writeOnly is not defined and "Properties marked as readOnly being true
+ * SHOULD NOT be in the required list").
+ *
+ * AutoRest Behavior:
+ * - required properties must be specified in the constructor.
+ * - required properties are non-nullable (unless x-nullable: true).
+ * - non-required properties are nullable (unless x-nullable: false).
+ * - validation is applied to non-null values in requests, not responses.
+ */
+export default class ReadOnlyNotRequiredTransformer
+  extends OpenApiTransformerBase {
+  constructor({ removeValidation, setNonNullable } = {}) {
+    super();
+
+    if (removeValidation !== undefined
+      && typeof removeValidation !== 'boolean') {
+      throw new TypeError('options.removeValidation must be boolean');
+    }
+
+    if (setNonNullable !== undefined
+      && typeof setNonNullable !== 'boolean') {
+      throw new TypeError('options.setNonNullable must be boolean');
+    }
+
+    this.options = {
+      removeValidation,
+      setNonNullable,
+    };
+  }
+
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    const { properties, required } = newSchema;
+    if (!properties || !Array.isArray(required) || required.length === 0) {
+      // No properties are defined or none are required
+      return newSchema;
+    }
+
+    const readOnlyNames = Object.keys(properties)
+      .filter((propName) => properties[propName].readOnly);
+    if (readOnlyNames.length === 0) {
+      // No readOnly properties
+      return newSchema;
+    }
+
+    const newRequired = required
+      .filter((propName) => !readOnlyNames.includes(propName));
+    if (newRequired.length === required.length) {
+      // No readOnly properties are required
+      return newSchema;
+    }
+
+    let newProperties = properties;
+    if (this.options.removeValidation || this.options.setNonNullable) {
+      newProperties = { ...properties };
+      const readOnlyRequired = required
+        .filter((propName) => readOnlyNames.includes(propName));
+      for (const readOnlyName of readOnlyRequired) {
+        const newProperty = { ...properties[readOnlyName] };
+
+        if (this.options.removeValidation) {
+          // FIXME: Should handle $ref, which is complicated
+          delete newProperty.exclusiveMaximum;
+          delete newProperty.exclusiveMinimum;
+          delete newProperty.maxItems;
+          delete newProperty.maxLength;
+          delete newProperty.maximum;
+          delete newProperty.minItems;
+          delete newProperty.minLength;
+          delete newProperty.minimum;
+          delete newProperty.multipleOf;
+          delete newProperty.pattern;
+        }
+
+        if (this.options.setNonNullable
+          && !Object.hasOwn(newProperty, 'x-nullable')) {
+          // Note: x-nullable: false is ignored for enum and class types
+          // FIXME: Adding x-nullable to $ref works in AutoRest (if $ref is to
+          // non-nullable type other than enum) but violates spec.
+          newProperty['x-nullable'] = false;
+        }
+
+        newProperties[readOnlyName] = newProperty;
+      }
+    }
+
+    const updatedSchema = {
+      ...newSchema,
+      properties: newProperties,
+      required: newRequired,
+    };
+    if (newRequired.length === 0) {
+      delete updatedSchema.required;
+    }
+    return updatedSchema;
+  }
+}

package/ref-path-parameters.js

@@ -0,0 +1,73 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/ref-path-parameters.js"
+ */
+
+// Note: Undocumented function which is part of the public API:
+// https://github.com/flitbit/json-ptr/issues/29
+import { encodeUriFragmentIdentifier } from 'json-ptr';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+import MatchingParameterManager from './lib/matching-parameter-manager.js';
+
+const parameterManagerSymbol = Symbol('parameterManager');
+const parametersPathSymbol = Symbol('parametersPath');
+
+/**
+ * Transformer to move Parameters defined on Path Item Objects to global
+ * parameters which are referenced in the Path Item so that Autorest will
+ * treat them as properties of the generated client, rather than method.
+ * https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-parameter-location
+ */
+export default class RefPathParametersTransformer
+  extends OpenApiTransformerBase {
+  transformParameter(param) {
+    if (!param || param.$ref) {
+      return param;
+    }
+
+    const defName =
+      this[parameterManagerSymbol].add(param, param.name);
+    return {
+      $ref: encodeUriFragmentIdentifier([
+        ...this[parametersPathSymbol],
+        defName,
+      ]),
+    };
+  }
+
+  transformPathItem(pathItem) {
+    if (!pathItem
+      || !Array.isArray(pathItem.parameters)
+      || pathItem.parameters.length === 0) {
+      return pathItem;
+    }
+
+    return {
+      ...pathItem,
+      parameters: pathItem.parameters.map(this.transformParameter.bind(this)),
+    };
+  }
+
+  transformOpenApi(spec) {
+    const newSpec = { ...spec };
+
+    if (spec.swagger) {
+      newSpec.parameters = { ...newSpec.parameters };
+      this[parameterManagerSymbol] =
+        new MatchingParameterManager(newSpec.parameters);
+      this[parametersPathSymbol] = ['parameters'];
+    } else {
+      newSpec.components = { ...newSpec.components };
+      newSpec.components.parameters = { ...newSpec.components.parameters };
+      this[parameterManagerSymbol] =
+        new MatchingParameterManager(newSpec.components.parameters);
+      this[parametersPathSymbol] = ['components', 'parameters'];
+    }
+
+    newSpec.paths = this.transformPaths(spec.paths);
+
+    return newSpec;
+  }
+}

package/remove-default-only-response-produces.js

@@ -0,0 +1,58 @@
+/**
+ * @copyright Copyright 2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/remove-default-only-response-produces.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to remove produces from operations with only a default response.
+ *
+ * If an operation only produces non-JSON types and only has a default response
+ * code, Autorest (core 2.0.4413 and 3.0.6246) will generate methods which do
+ * not return a value.  If the operation does not produce any types, Autorest
+ * will generate a method which returns the response value (e.g. Stream for
+ * type: file).
+ */
+export default class RemoveDefaultOnlyResponseProducesTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformOperation(operation) {
+    if (!operation || !operation.responses) {
+      return operation;
+    }
+
+    const codes = Object.keys(operation.responses);
+    if (codes.length !== 1 || codes[0] !== 'default') {
+      return operation;
+    }
+
+    return {
+      ...operation,
+      // Note: empty produces is required to override global produces (if any)
+      produces: [],
+    };
+  }
+
+  transformOpenApi(openApi) {
+    // There is no way to remove response media types in OpenAPI 3 without
+    // removing the schema type (which is what we are trying to return).
+    if (!openApi || openApi.swagger !== '2.0') {
+      throw new Error(
+        `${this.constructor.name} can only be applied to OpenAPI 2.0 documents`,
+      );
+    }
+
+    // Optimization: not calling super.transformOpenApi since only .paths
+    // needs to be transformed.
+    if (openApi.paths === undefined) {
+      return openApi;
+    }
+
+    return {
+      ...openApi,
+      paths: this.transformPaths(openApi.paths),
+    };
+  }
+}

package/remove-paths-with-servers.js

@@ -0,0 +1,34 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/remove-paths-with-servers.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to remove Path Item Objects which have servers (and therefore
+ * can't be represented in OpenAPI 2).
+ */
+export default class RemovePathsWithServersTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformPaths(paths) {
+    return Object.keys(paths)
+      .reduce((newPaths, path) => {
+        const pathItem = paths[path];
+        if (!pathItem.servers) {
+          newPaths[path] = pathItem;
+        }
+        return newPaths;
+      }, Object.create(Object.getPrototypeOf(paths)));
+  }
+
+  // Optimization: Only transform paths
+  transformOpenApi(spec) {
+    return {
+      ...spec,
+      paths: this.transformPaths(spec.paths),
+    };
+  }
+}