@kevinoid/openapi-transformers 0.1.0

package/exclusive-min-max-to-bool.js

@@ -0,0 +1,61 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/exclusive-min-max-to-bool.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to convert Schema Objects with numeric values for
+ * `exclusiveMaximum` and/or `exclusiveMinimum` (as in JSON Schema Draft
+ * 2020-12 referenced by OAS 3.1.0:
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.2.3
+ * ) to boolean values with corresponding `maximum` and/or `minimum` (as in
+ * JSON Schema Write 00 referenced by OAS 3.0:
+ * https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-5.3
+ * and JSON Schema Draft 4 referenced by OAS 2:
+ * https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00#section-5.1.2
+ * ).
+ */
+export default class ExclusiveMinMaxToBoolTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    schema = super.transformSchema(schema);
+    if (schema === null
+      || typeof schema !== 'object'
+      || Array.isArray(schema)) {
+      return schema;
+    }
+
+    const exclusiveMaximum = +schema.exclusiveMaximum;
+    const exclusiveMinimum = +schema.exclusiveMinimum;
+    if (Number.isNaN(exclusiveMaximum) && Number.isNaN(exclusiveMinimum)) {
+      return schema;
+    }
+
+    const newSchema = { ...schema };
+
+    if (!Number.isNaN(exclusiveMaximum)) {
+      const { maximum } = schema;
+      if (maximum < exclusiveMaximum) {
+        delete newSchema.exclusiveMaximum;
+      } else {
+        newSchema.maximum = exclusiveMaximum;
+        newSchema.exclusiveMaximum = true;
+      }
+    }
+
+    if (!Number.isNaN(exclusiveMinimum)) {
+      const { minimum } = schema;
+      if (minimum > exclusiveMinimum) {
+        delete newSchema.exclusiveMinimum;
+      } else {
+        newSchema.minimum = exclusiveMinimum;
+        newSchema.exclusiveMinimum = true;
+      }
+    }
+
+    return newSchema;
+  }
+}

package/format-to-type.js

@@ -0,0 +1,54 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/format-to-type.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+function transformSchemaType(schema) {
+  if (schema.type === 'string') {
+    const formatToType = {
+      decimal: 'number',
+      double: 'number',
+      float: 'number',
+      integer: 'integer',
+      int32: 'integer',
+      int64: 'integer',
+    };
+    const newType = formatToType[schema.format];
+    if (newType) {
+      const newSchema = {
+        ...schema,
+        type: newType,
+      };
+      if (newSchema.format === 'integer') {
+        // format: integer is redundant with type: integer
+        delete newSchema.format;
+      }
+      return newSchema;
+    }
+  }
+
+  return schema;
+}
+
+/**
+ * Transformer to convert known formats in an OAS3 doc to types (for Autorest).
+ *
+ * Autorest doesn't generate int/decimal/double properties for type: string.
+ * Change the type to generate as desired.
+ */
+export default class FormatToTypeTransformer extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    return transformSchemaType(super.transformSchema(schema));
+  }
+
+  transformParameter(parameter) {
+    return transformSchemaType(super.transformParameter(parameter));
+  }
+
+  transformHeader(header) {
+    return transformSchemaType(super.transformHeader(header));
+  }
+}

package/index.js

@@ -0,0 +1,94 @@
+/**
+ * @copyright Copyright 2024 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers"
+ */
+
+/* eslint-disable import/no-unused-modules */
+
+export { default as AdditionalPropertiesToObjectTransformer }
+  from './additional-properties-to-object.js';
+export { default as AdditionalPropertiesToUnconstrainedTransformer }
+  from './additional-properties-to-unconstrained.js';
+export { default as AddTagToOperationIdsTransformer }
+  from './add-tag-to-operation-ids.js';
+export { default as AddXMsEnumNameTransformer }
+  from './add-x-ms-enum-name.js';
+export { default as AddXMsEnumValueNamesTransformer }
+  from './add-x-ms-enum-value-names.js';
+export { default as AnyOfNullToNullableTransformer }
+  from './any-of-null-to-nullable.js';
+export { default as AssertPropertiesTransformer }
+  from './assert-properties.js';
+export { default as BinaryStringToFileTransformer }
+  from './binary-string-to-file.js';
+export { default as BoolEnumToBoolTransformer }
+  from './bool-enum-to-bool.js';
+export { default as ClearHtmlResponseSchemaTransformer }
+  from './clear-html-response-schema.js';
+export { default as ClientParamsToGlobalTransformer }
+  from './client-params-to-global.js';
+export { default as ConstToEnumTransformer }
+  from './const-to-enum.js';
+export { default as EscapeEnumValuesTransformer }
+  from './escape-enum-values.js';
+export { default as ExclusiveMinMaxToBoolTransformer }
+  from './exclusive-min-max-to-bool.js';
+export { default as FormatToTypeTransformer }
+  from './format-to-type.js';
+export { default as InlineNonObjectSchemaTransformer }
+  from './inline-non-object-schemas.js';
+export { default as MergeAllOfTransformer }
+  from './merge-all-of.js';
+export { default as MergeAnyOfTransformer }
+  from './merge-any-of.js';
+export { default as MergeOneOfTransformer }
+  from './merge-one-of.js';
+export { default as NullableNotRequiredTransformer }
+  from './nullable-not-required.js';
+export { default as NullableToTypeNullTransformer }
+  from './nullable-to-type-null.js';
+export { default as OpenApi31To30Transformer }
+  from './openapi31to30.js';
+export { default as PathParametersToOperationTransformer }
+  from './path-parameters-to-operations.js';
+export { default as PatternPropertiesToAdditionalPropertiesTransformer }
+  from './pattern-properties-to-additional-properties.js';
+export { default as QueriesToXMsPathsTransformer }
+  from './queries-to-x-ms-paths.js';
+export { default as ReadOnlyNotRequiredTransformer }
+  from './read-only-not-required.js';
+export { default as RefPathParametersTransformer }
+  from './ref-path-parameters.js';
+export { default as RemoveDefaultOnlyResponseProducesTransformer }
+  from './remove-default-only-response-produces.js';
+export { default as RemovePathsWithServersTransformer }
+  from './remove-paths-with-servers.js';
+export { default as RemoveQueryFromPathsTransformer }
+  from './remove-query-from-paths.js';
+export { default as RemoveRefSiblingsTransformer }
+  from './remove-ref-siblings.js';
+export { default as RemoveRequestBodyTransformer }
+  from './remove-request-body.js';
+export { default as RemoveResponseHeadersTransformer }
+  from './remove-response-headers.js';
+export { default as RemoveSecuritySchemeIfTransformer }
+  from './remove-security-scheme-if.js';
+export { default as RemoveTypeIfTransformer }
+  from './remove-type-if.js';
+export { default as RenameComponentsTransformer }
+  from './rename-components.js';
+export { default as ReplacedByToDescriptionTransformer }
+  from './replaced-by-to-description.js';
+export { default as ServerVarsToPathParamsTransformer }
+  from './server-vars-to-path-params.js';
+export { default as ServerVarsToParamHostTransformer }
+  from './server-vars-to-x-ms-parameterized-host.js';
+export { default as TypeNullToEnumTransformer }
+  from './type-null-to-enum.js';
+export { default as TypeNullToNullableTransformer }
+  from './type-null-to-nullable.js';
+export { default as UrlencodedToStringTransformer }
+  from './urlencoded-to-string.js';
+export { default as XEnumToXMsEnumTransformer }
+  from './x-enum-to-ms.js';

package/inline-non-object-schemas.js

@@ -0,0 +1,120 @@
+/**
+ * @copyright Copyright 2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/inline-non-object-schemas.js"
+ */
+
+import { debuglog } from 'node:util';
+
+import { JsonPointer } from 'json-ptr';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const debug = debuglog('inline-non-object-schemas');
+
+const inlineAllSymbol = Symbol('inlineAll');
+const resolveRefSymbol = Symbol('resolveRef');
+
+// JSON Schema validation keywords supported by Autorest which must be inlined
+// https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/mgmtcommon/ClientRuntime/ClientRuntime/ValidationRules.cs
+// Note: exclusiveMaximum/Minimum only modify maximum/minimum validation.
+const validationKeywords = {
+  maxItems: true,
+  maxLength: true,
+  maximum: true,
+  minItems: true,
+  minLength: true,
+  minimum: true,
+  multipleOf: true,
+  pattern: true,
+  uniqueItems: true,
+};
+
+/**
+ * Transformer to inline schemas with non-object type so that Autorest will
+ * generate validation code.
+ *
+ * https://github.com/Azure/autorest.csharp/issues/795
+ */
+export default class InlineNonObjectSchemaTransformer
+  extends OpenApiTransformerBase {
+  constructor({ inlineAll, resolveRef } = {}) {
+    super();
+
+    if (resolveRef !== undefined && typeof resolveRef !== 'function') {
+      throw new TypeError('resolveRef must be a function');
+    }
+
+    this[inlineAllSymbol] = Boolean(inlineAll);
+    this[resolveRefSymbol] = resolveRef;
+  }
+
+  transformSchema(schema) {
+    const { $ref, ...nonRef } = schema;
+    if (typeof $ref !== 'string') {
+      return super.transformSchema(schema);
+    }
+
+    const refSchema = this[resolveRefSymbol]($ref);
+    if (refSchema === undefined) {
+      debug('Unable to resolve $ref %s', $ref);
+      return super.transformSchema(schema);
+    }
+
+    if (!refSchema || !refSchema.type || refSchema.type === 'object') {
+      debug('Not inlining %s: type %s', $ref, refSchema && refSchema.type);
+      return super.transformSchema(schema);
+    }
+
+    if (refSchema.enum) {
+      debug('Not inlining %s: enum', $ref);
+      return super.transformSchema(schema);
+    }
+
+    if (!this[inlineAllSymbol]
+      && !Object.keys(refSchema).some((prop) => validationKeywords[prop])
+      // exclusiveMaximum/exclusiveMinimum are numbers in JSON Schema
+      // Draft 2020-12 referenced by OAS 3.1.0 and apply on their own:
+      // https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.2.3
+      // exclusiveMaximum/exclusiveMinimum are boolean in JSON Schema Write 00
+      // referenced by OAS 3.0:
+      // https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-5.3
+      // and JSON Schema Draft 4 referenced by OAS 2:
+      // https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00#section-5.1.2
+      // which only affect minimum/maximum and have no effect on their own.
+      && typeof refSchema.exclusiveMaximum !== 'number'
+      && typeof refSchema.exclusiveMinimum !== 'number') {
+      debug(
+        'Not inlining %s: No validation keywords require inlining',
+        $ref,
+      );
+      return super.transformSchema(schema);
+    }
+
+    debug('Inlining %s.', $ref);
+    return {
+      ...super.transformSchema(refSchema),
+      // Like Autorest, allow properties other than $ref
+      ...nonRef,
+    };
+  }
+
+  transformOpenApi(openapi) {
+    // If resolveRefSymbol was not set from options, resolve against OpenAPI
+    // Object being transformed.
+    const optResolve = this[resolveRefSymbol];
+    if (!optResolve) {
+      this[resolveRefSymbol] = function resolveRef($ref) {
+        // JsonPointer.get would throw for non-local refs
+        return $ref[0] === '#' ? JsonPointer.get(openapi, $ref) : undefined;
+      };
+    }
+
+    try {
+      return super.transformOpenApi(openapi);
+    } finally {
+      if (optResolve) {
+        this[resolveRefSymbol] = optResolve;
+      }
+    }
+  }
+}

package/lib/component-manager.js

@@ -0,0 +1,60 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ */
+
+import { isDeepStrictEqual } from 'node:util';
+
+/** Manages named additions to defined components.
+ */
+export default class ComponentManager {
+  constructor(component) {
+    if (component === null
+      || typeof component !== 'object'
+      || Array.isArray(component)) {
+      throw new TypeError('component must be a non-Array, non-null object');
+    }
+
+    this.component = component;
+  }
+
+  /** Adds a given value, optionally with a given (base) name.
+   *
+   * @param {*} value Value to add to the component being managed.
+   * @param {string=} basename Preferred name for value in component.
+   * ({@link getNames}).
+   * @returns {string} Name of added value.
+   */
+  add(value, basename) {
+    for (const name of this.getNames(basename)) {
+      if (this.component[name] === undefined) {
+        this.component[name] = value;
+        return name;
+      }
+
+      if (this.isMatch(this.component[name], value)) {
+        return name;
+      }
+    }
+
+    throw new Error('No suitable name matched value to add');
+  }
+
+  /** Gets property names to check for a given base name.
+   *
+   * @param {string=} basename Base name to use for property.
+   * @yields {string} Property names to check for #add().
+   */
+  // eslint-disable-next-line class-methods-use-this
+  * getNames(basename) {
+    yield `${basename}`;
+    for (let i = 2; ; i += 1) {
+      yield `${basename}${i}`;
+    }
+  }
+}
+
+/** Determines if given values match such that an existing value can be used in
+ * place of an added value.
+ */
+ComponentManager.prototype.isMatch = isDeepStrictEqual;

package/lib/matching-component-manager.js

@@ -0,0 +1,74 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ */
+
+// Any unique, deterministic stringify function would work.
+// TODO: Benchmark against native JSON.stringify result of sort-keys deep
+// https://github.com/sindresorhus/getKey-obj/blob/master/index.js#L17
+// https://github.com/epoberezkin/fast-json-stable-stringify#benchmark
+import stringify from 'fast-json-stable-stringify';
+
+import ComponentManager from './component-manager.js';
+
+const keyToNameSymbol = Symbol('keyToName');
+
+/** Adds values to defined components by first attempting to match an
+ * existing value in the component.
+ */
+export default class MatchingComponentManager extends ComponentManager {
+  constructor(component) {
+    super(component);
+
+    const keyToName = new Map();
+    for (const [name, value] of Object.entries(component)) {
+      keyToName.set(this.getKey(value), name);
+    }
+    this[keyToNameSymbol] = keyToName;
+  }
+
+  /** Adds a given value, optionally with a given (base) name.
+   *
+   * @param {*} value Value to add to the component being managed.
+   * @param {string=} basename Preferred name for value in component.
+   * ({@link ComponentManager#getNames}).
+   * @returns {string} Name of added value.
+   */
+  add(value, basename) {
+    const key = this.getKey(value);
+    const name = this[keyToNameSymbol].get(key);
+    if (name) {
+      return name;
+    }
+
+    const newName = super.add(value, basename);
+    this[keyToNameSymbol].set(key, newName);
+    return newName;
+  }
+
+  /** Determines if given values match such that an existing value can be used
+   * in place of an added value.
+   *
+   * Overridden to always return false, since values which do not have equal
+   * keys do not match (according to this class) and keys are checked before
+   * calling super.add().
+   *
+   * FIXME: This optimization is useful to avoid wasting lots of cycles
+   * for properties with many name conflicts with deep values, but it is
+   * also a foot-gun if isMatch is called unexpectedly.  Find a better fix.
+   *
+   * @returns {boolean} False.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  isMatch() {
+    return false;
+  }
+}
+
+/** Converts a value to an key which uniquely identifies the value for
+ * matching.
+ *
+ * @param {*} value Value to identify.
+ * @returns {*} Key which uniquely matches the value.
+ */
+MatchingComponentManager.prototype.getKey = stringify;

package/lib/matching-parameter-manager.js

@@ -0,0 +1,36 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ */
+
+import MatchingComponentManager from './matching-component-manager.js';
+
+/** Gets a copy of a parameter with x-ms-parameter-location removed if
+ * its value is 'client'.
+ *
+ * Autorest treats defined parameters as properties on the client by default.
+ * (i.e. the same as x-ms-parameter-location:client)  Therefore, remove
+ * x-ms-parameter-location:client when comparing/keying parameters so
+ * it doesn't affect equality.
+ *
+ * @param {object=} parameter Parameter Object to strip.
+ * @returns {object=} Copy of parameter with x-ms-parameter-location removed if
+ * its value is 'client'.  Otherwise, parameter.
+ */
+function stripClientXMsParamLoc(parameter) {
+  if (parameter && parameter['x-ms-parameter-location'] === 'client') {
+    const { 'x-ms-parameter-location': _, ...paramNoLoc } = parameter;
+    return paramNoLoc;
+  }
+
+  return parameter;
+}
+
+/** Adds values to defined components by first attempting to match an
+ * existing value in the component.
+ */
+export default class MatchingParameterManager extends MatchingComponentManager {
+  getKey(parameter) {
+    return super.getKey(stripClientXMsParamLoc(parameter));
+  }
+}

package/merge-all-of.js

@@ -0,0 +1,60 @@
+/**
+ * @copyright Copyright 2021, 2025 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/merge-all-of.js"
+ */
+
+import { debuglog } from 'node:util';
+
+import intersectSchema from 'json-schema-intersect';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const debug = debuglog('openapi-transformers:merge-all-of');
+
+/**
+ * Transformer to merge allOf schemas into the parent schema.
+ *
+ * This may be useful to accommodate tools which do not support allOf well
+ * (e.g. some strongly-typed code generators).
+ */
+export default class MergeAllOfTransformer extends OpenApiTransformerBase {
+  onlySingle = false;
+
+  constructor({ onlySingle } = {}) {
+    super();
+
+    this.onlySingle = Boolean(onlySingle);
+  }
+
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (!newSchema || typeof newSchema !== 'object') {
+      // Note: warning already emitted by super.transformSchema()
+      return newSchema;
+    }
+
+    const {
+      allOf,
+      ...schemaNoAllOf
+    } = newSchema;
+    if (!Array.isArray(allOf)) {
+      this.warn('Unable to merge non-Array allOf', allOf);
+      return newSchema;
+    }
+
+    if (allOf.length === 0) {
+      // Empty allOf Array is disallowed by JSON Schema.
+      // Considered safe to remove since any instance trivially validates
+      // successfully against all 0 schemas.
+      debug('Removing empty allOf');
+      return schemaNoAllOf;
+    }
+
+    if (this.onlySingle && allOf.length > 1) {
+      debug('Skipping allOf with multiple schemas');
+      return newSchema;
+    }
+
+    return allOf.reduce(intersectSchema, schemaNoAllOf);
+  }
+}

package/merge-any-of.js

@@ -0,0 +1,48 @@
+/**
+ * @copyright Copyright 2021, 2025 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/merge-any-of.js"
+ */
+
+import intersectSchema from 'json-schema-intersect';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to merge anyOf schemas into the parent schema.
+ *
+ * This is useful for converting to OpenAPI 2.0 (which does not support
+ * anyOf) from later versions, or to accommodate tools which do not support
+ * anyOf well (e.g. many strongly-typed code generators).
+ */
+export default class MergeAnyOfTransformer extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (!newSchema || typeof newSchema !== 'object') {
+      // Note: warning already emitted by super.transformSchema()
+      return newSchema;
+    }
+
+    const {
+      anyOf,
+      ...schemaNoAnyOf
+    } = newSchema;
+    if (!Array.isArray(anyOf)) {
+      this.warn('Unable to merge non-Array anyOf', anyOf);
+      return newSchema;
+    }
+
+    if (anyOf.length === 0) {
+      // Empty anyOf Array is disallowed by JSON Schema.
+      // Not safe to remove since all instances will fail to "validate
+      // successfully against at least one schema".
+      this.warn('Unable to merge empty anyOf Array');
+      return newSchema;
+    }
+
+    if (anyOf.length > 1) {
+      throw new Error('Merging multiple anyOf schemas not implemented');
+    }
+
+    return intersectSchema(schemaNoAnyOf, anyOf[0]);
+  }
+}

package/merge-one-of.js

@@ -0,0 +1,48 @@
+/**
+ * @copyright Copyright 2021, 2025 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/merge-one-of.js"
+ */
+
+import intersectSchema from 'json-schema-intersect';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to merge oneOf schemas into the parent schema.
+ *
+ * This is useful for converting to OpenAPI 2.0 (which does not support
+ * oneOf) from later versions, or to accommodate tools which do not support
+ * oneOf well (e.g. many strongly-typed code generators).
+ */
+export default class MergeOneOfTransformer extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (!newSchema || typeof newSchema !== 'object') {
+      // Note: warning already emitted by super.transformSchema()
+      return newSchema;
+    }
+
+    const {
+      oneOf,
+      ...schemaNoOneOf
+    } = newSchema;
+    if (!Array.isArray(oneOf)) {
+      this.warn('Unable to merge non-Array oneOf', oneOf);
+      return newSchema;
+    }
+
+    if (oneOf.length === 0) {
+      // Empty oneOf Array is disallowed by JSON Schema.
+      // Not safe to remove since all instances will fail to "validate
+      // successfully against exactly one schema".
+      this.warn('Unable to merge empty oneOf Array');
+      return newSchema;
+    }
+
+    if (oneOf.length > 1) {
+      throw new Error('Merging multiple oneOf schemas not implemented');
+    }
+
+    return intersectSchema(schemaNoOneOf, oneOf[0]);
+  }
+}