@kevinoid/openapi-transformers 0.1.0

package/assert-properties.js

@@ -0,0 +1,56 @@
+/**
+ * @copyright Copyright 2025 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/assert-properties.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer which throws an Error when given properties are present in the
+ * OpenAPI document.
+ */
+export default class AssertPropertiesTransformer
+  extends OpenApiTransformerBase {
+  options = {};
+
+  constructor(options) {
+    super();
+
+    if (typeof options !== 'object' || options === null) {
+      throw new TypeError('options must be an object');
+    }
+
+    if (typeof options.schema !== 'object' || options.schema === null) {
+      throw new TypeError('options.schema must be an object');
+    }
+
+    if (!Array.isArray(options.schema.excludes)) {
+      throw new TypeError('options.schema.excludes must be an Array');
+    }
+
+    if (!options.schema.excludes.every((s) => typeof s === 'string')) {
+      throw new TypeError(
+        'options.schema.excludes must only contain property names',
+      );
+    }
+
+    this.options = options;
+  }
+
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (typeof newSchema !== 'object' || newSchema === null) {
+      return newSchema;
+    }
+
+    for (const propName of this.options.schema.excludes) {
+      if (newSchema[propName] !== undefined
+        && Object.hasOwn(newSchema, propName)) {
+        throw new Error(`Schema contains ${propName}`);
+      }
+    }
+
+    return newSchema;
+  }
+}

package/binary-string-to-file.js

@@ -0,0 +1,54 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/binary-string-to-file.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+function transformSchemaType(schema) {
+  if (schema.type === 'string'
+    && (schema.format === 'binary' || schema.format === 'file')) {
+    const newSchema = {
+      ...schema,
+      type: 'file',
+    };
+    delete newSchema.format;
+    return newSchema;
+  }
+
+  return schema;
+}
+
+/**
+ * Transformer to replace `type: string, format: binary` (or `format: file`)
+ * with `type: file` so that Autorest generates to a Stream instead of string.
+ */
+export default class BinaryStringToFileTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformSchema(schema) {
+    // Don't call super, since `type: file` is only allowed on root schema of
+    // response.
+    // Note: No checking is done to enforce this (due to $ref complications).
+    // Note: A response could $ref a property schema.  Unlikely.
+    return transformSchemaType(schema);
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  transformParameter(parameter) {
+    if (parameter === null || typeof parameter !== 'object') {
+      return parameter;
+    }
+
+    let newParameter = transformSchemaType(parameter);
+    if (newParameter.schema) {
+      newParameter = {
+        ...newParameter,
+        schema: transformSchemaType(newParameter.schema),
+      };
+    }
+
+    return newParameter;
+  }
+}

package/bool-enum-to-bool.js

@@ -0,0 +1,100 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/bool-enum-to-bool.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const inStringContextSymbol = Symbol('inStringContext');
+
+/**
+ * Transformer to replace `enum: [true, false]` with `type: boolean` for
+ * simplicity and to assist generators.
+ */
+export default class BoolEnumToBoolTransformer
+  extends OpenApiTransformerBase {
+  constructor() {
+    super();
+    this[inStringContextSymbol] = false;
+  }
+
+  transformSchemaLike(schema) {
+    if (schema === null
+      || typeof schema !== 'object'
+      || Array.isArray(schema)) {
+      return schema;
+    }
+
+    const { enum: enumValues, ...schemaNoEnum } = schema;
+    if (!Array.isArray(enumValues) || enumValues.length < 2) {
+      return schema;
+    }
+
+    const { type } = schema;
+    if (!this[inStringContextSymbol]
+      && type !== 'boolean'
+      && !enumValues.every((ev) => typeof ev === 'boolean')) {
+      // If schema validates non-boolean values in a type-sensitive context,
+      // limiting to boolean would change validation.
+      return schema;
+    }
+
+    if (!(enumValues.includes(true) || enumValues.includes('true'))
+      || !(enumValues.includes(false) || enumValues.includes('false'))
+      || enumValues.some((ev) => ev !== true
+        && ev !== false
+        && ev !== 'true'
+        && ev !== 'false')) {
+      // Enum must contain both true and false, and only true/false
+      return schema;
+    }
+
+    schemaNoEnum.type = 'boolean';
+
+    return schemaNoEnum;
+  }
+
+  transformSchema(schema) {
+    return this.transformSchemaLike(super.transformSchema(schema));
+  }
+
+  transformItems(items) {
+    return this.transformSchemaLike(super.transformItems(items));
+  }
+
+  transformHeader(header) {
+    const prevContext = this[inStringContextSymbol];
+    try {
+      this[inStringContextSymbol] = true;
+      return this.transformSchemaLike(super.transformHeader(header));
+    } finally {
+      this[inStringContextSymbol] = prevContext;
+    }
+  }
+
+  transformParameter(parameter) {
+    const prevContext = this[inStringContextSymbol];
+    try {
+      this[inStringContextSymbol] = parameter.in !== 'body';
+      return this.transformSchemaLike(super.transformParameter(parameter));
+    } finally {
+      this[inStringContextSymbol] = prevContext;
+    }
+  }
+
+  transformMediaType(mediaType) {
+    const prevContext = this[inStringContextSymbol];
+    const mediaTypeStr = this.transformPath.at(-1);
+    try {
+      this[inStringContextSymbol] =
+        mediaTypeStr === 'application/x-www-form-urlencoded'
+        || mediaTypeStr === 'multipart/form-data'
+        || mediaTypeStr === 'text/csv'
+        || mediaTypeStr === 'text/plain';
+      return super.transformMediaType(mediaType);
+    } finally {
+      this[inStringContextSymbol] = prevContext;
+    }
+  }
+}

package/clear-html-response-schema.js

@@ -0,0 +1,77 @@
+/**
+ * @copyright Copyright 2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/clear-html-response-schema.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+function isHtml(mediaType) {
+  return /^\s*text\/html\s*(?:;.*)?$/i.test(mediaType);
+}
+
+/**
+ * Transformer to remove response content for the text/html media type.
+ *
+ * Autorest does not provide a good way to consume text/html:
+ * - If the schema has type: string (with or without format: binary), the
+ *   generated method attempts to JSON-decode the HTML, which fails.
+ * - If the schema has type: file, Autorest calls HttpContent.ReadAsStreamAsync
+ *   and returns the Stream, which complicates conversion to string, since the
+ *   caller can't call HttpContent.ReadAsStringAsync (which would cause
+ *   "InvalidOperationException: The stream was already consumed. It cannot be
+ *   read again.") and must reimplement charset detection to use on Stream.
+ */
+export default class ClearHtmlResponseSchemaTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformResponse(response) {
+    if (!response) {
+      return response;
+    }
+
+    let newResponse = response;
+
+    // Remove schema from OpenAPI 3 Media Type Objects
+    const { content, schema } = newResponse;
+    if (content) {
+      const htmlTypes = Object.keys(content).filter(isHtml);
+      if (htmlTypes.length > 0) {
+        const newContent = { ...content };
+        for (const htmlType of htmlTypes) {
+          const newMediaType = { ...content[htmlType] };
+          delete newMediaType.schema;
+          delete newMediaType.encoding;
+          newContent[htmlType] = newMediaType;
+        }
+        newResponse = {
+          ...newResponse,
+          content: newContent,
+        };
+      }
+    }
+
+    // Remove schema from OpenAPI 2 response.schema
+    if (schema !== undefined) {
+      newResponse = { ...newResponse };
+      delete newResponse.schema;
+    }
+
+    return newResponse;
+  }
+
+  transformOperation(operation) {
+    if (!operation || !operation.responses) {
+      return operation;
+    }
+
+    // Only transform OpenAPI 2.0 if the operation only produces HTML
+    // (since one schema is shared by all)
+    const { produces } = operation;
+    if (Array.isArray(produces) && !produces.every(isHtml)) {
+      return operation;
+    }
+
+    return super.transformOperation(operation);
+  }
+}

package/client-params-to-global.js

@@ -0,0 +1,97 @@
+/**
+ * @copyright Copyright 2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/client-params-to-global.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 with x-ms-parameter-location:client defined on
+ * Path Item Objects and Operation Objects to the Components or Definitions
+ * Object (which is required for x-ms-parameter-location to have any effect).
+ *
+ * Note: Authors should define such parameters in Components or Definitions.
+ * This script is mostly a workaround for api-spec-converter, which inlines
+ * all $ref parameters.
+ * https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-parameter-location
+ */
+export default class ClientParamsToGlobalTransformer
+  extends OpenApiTransformerBase {
+  transformParameter(parameter) {
+    if (!parameter || parameter['x-ms-parameter-location'] !== 'client') {
+      return parameter;
+    }
+
+    const defName = this[parameterManagerSymbol].add(parameter, parameter.name);
+    return {
+      $ref: encodeUriFragmentIdentifier([
+        ...this[parametersPathSymbol],
+        defName,
+      ]),
+    };
+  }
+
+  transformOpenApi(openApi) {
+    if (typeof openApi !== 'object' || openApi === null || !openApi.paths) {
+      return openApi;
+    }
+
+    const { components, openapi, paths } = openApi;
+    if (/^3(?:\.|$)/.test(openapi)
+      || (typeof components === 'object' && components !== null)) {
+      const newParameters = { ...components && components.parameters };
+      this[parameterManagerSymbol] =
+        new MatchingParameterManager(newParameters);
+      this[parametersPathSymbol] = ['components', 'parameters'];
+
+      return {
+        ...openApi,
+        components: {
+          ...components,
+          parameters: newParameters,
+        },
+        paths: this.transformPaths(paths),
+      };
+    }
+
+    const { parameters, swagger } = openApi;
+    if (/^2(?:\.|$)/.test(swagger)
+      || (typeof parameters === 'object' && parameters !== null)) {
+      const newParameters = { ...parameters };
+      this[parameterManagerSymbol] =
+        new MatchingParameterManager(newParameters);
+      this[parametersPathSymbol] = ['parameters'];
+
+      const newOpenApi = {
+        ...openApi,
+        parameters: newParameters,
+        paths: this.transformPaths(openApi.paths),
+      };
+
+      const xMsParameterizedHost = openApi['x-ms-parameterized-host'];
+      if (xMsParameterizedHost
+        && Array.isArray(xMsParameterizedHost.parameters)) {
+        newOpenApi['x-ms-parameterized-host'] = {
+          ...xMsParameterizedHost,
+          parameters: this.transformArray(
+            xMsParameterizedHost.parameters,
+            this.transformParameter,
+          ),
+        };
+      }
+
+      return newOpenApi;
+    }
+
+    return openApi;
+  }
+}

package/const-to-enum.js

@@ -0,0 +1,49 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/const-to-enum.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to convert Schema Objects with `const` (as in OAS 3.1 and JSON
+ * Schema) to `enum` for OAS 3.0 and 2.0.
+ */
+export default class ConstToEnumTransformer extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (newSchema === null
+      || typeof newSchema !== 'object'
+      || Array.isArray(newSchema)) {
+      return newSchema;
+    }
+
+    const { const: constValue, ...schemaNoConst } = newSchema;
+    if (constValue === undefined) {
+      return newSchema;
+    }
+
+    const enumValues = schemaNoConst.enum;
+    if (enumValues === undefined) {
+      schemaNoConst.enum = [constValue];
+    } else if (Array.isArray(enumValues)) {
+      if (enumValues.includes(constValue)) {
+        // Schema validation would only succeed for const value.
+        // Safe to overwrite.
+        schemaNoConst.enum = [constValue];
+      } else if (enumValues.length > 0) {
+        // Schema validation would always fail (because either const or enum
+        // constraint would be unsatisfied).  Replace with empty enum, which
+        // also always fails.
+        this.warn(
+          'Using empty enum for schema with const not in enum',
+          newSchema,
+        );
+        schemaNoConst.enum = [];
+      }
+    }
+
+    return schemaNoConst;
+  }
+}

package/escape-enum-values.js

@@ -0,0 +1,211 @@
+/**
+ * @copyright Copyright 2019-2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/escape-enum-values.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const escapeStringSymbol = Symbol('escapeString');
+
+function makeEscapeString(lang) {
+  let charToEscape = {
+    '\0': '\\0',
+    '\x07': '\\a',
+    '\b': '\\b',
+    '\t': '\\t',
+    '\n': '\\n',
+    '\v': '\\v',
+    '\f': '\\f',
+    '\r': '\\r',
+    "'": "\\'",
+    '"': '\\"',
+    '\\': '\\\\',
+  };
+  // Escape control characters for all languages for readability
+  let charRange = '\0-\x1F\x7F';
+
+  let toAstralEscape, toCodeEscape;
+  switch (lang) {
+    case 'csharp':
+      // https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/lexical-structure#string-literals
+      charRange += '\n\r"\\\\\x85\u2028\u2029';
+      // Note: Although \x can be shorter, must be careful to provide 4
+      // digits when next character is hex digit.  Use \u for consistency.
+      toCodeEscape =
+        (c) => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`;
+      toAstralEscape = (code) => `\\U${code.toString(16).padStart(8, '0')}`;
+      break;
+
+    case 'go':
+      // https://golang.org/ref/spec#String_literals
+      charRange += '\n"\\\\';
+      toCodeEscape = (c) => {
+        const code = c.codePointAt(0);
+        return code <= 0xFF ? `\\x${code.toString(16).padStart(2, '0')}`
+          : `\\u${code.toString(16).padStart(4, '0')}`;
+      };
+      toAstralEscape = (code) => `\\U${code.toString(16).padStart(8, '0')}`;
+      break;
+
+    case 'java':
+      // https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.10.5
+      charRange += '\n"\\\\';
+      delete charToEscape['\0'];
+      delete charToEscape['\x07'];
+      delete charToEscape['\v'];
+      toCodeEscape =
+        (c) => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`;
+      break;
+
+    case 'nodejs':
+    case 'typescript':
+      // https://www.ecma-international.org/ecma-262/6.0/#sec-literals-string-literals
+      // Note: AutoRest currently produces single-quoted strings, but the
+      // bloat from extra quoting is minor compared to risk.
+      charRange += '\n"\'\\\\';
+      delete charToEscape['\x07'];
+      toCodeEscape = (c) => {
+        const code = c.codePointAt(0);
+        return code <= 0xFF ? `\\x${code.toString(16).padStart(2, '0')}`
+          : `\\u${code.toString(16).padStart(4, '0')}`;
+      };
+      toAstralEscape = (code) => `\\u{${code.toString(16)}}`;
+      break;
+
+    case 'php':
+      // https://www.php.net/manual/en/language.types.string.php
+      // FIXME: Does AutoRest produce single- or double-quoted strings?
+      // Can't test due to https://github.com/Azure/autorest/issues/3372
+      charRange += '\n"\\\\';
+      delete charToEscape['\x07'];
+      delete charToEscape['\b'];
+      charToEscape['\x1B'] = '\\e';
+      toCodeEscape = (c) => {
+        const code = c.codePointAt(0);
+        return code <= 0xFF ? `\\x${code.toString(16).padStart(2, '0')}`
+          : `\\u{${code.toString(16)}}`;
+      };
+      toAstralEscape = (code) => `\\u{${code.toString(16)}}`;
+      break;
+
+    case 'python':
+      // https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals
+      // Note: AutoRest currently produces single-quoted strings, but the
+      // bloat from extra quoting is minor compared to risk.
+      charRange += '\n"\'\\\\';
+      toCodeEscape = (c) => {
+        const code = c.codePointAt(0);
+        return code <= 0xFF ? `\\x${code.toString(16).padStart(2, '0')}`
+          : `\\u${code.toString(16).padStart(4, '0')}`;
+      };
+      toAstralEscape = (code) => `\\U${code.toString(16).padStart(8, '0')}`;
+      break;
+
+    case 'ruby':
+      // Note: AutoRest currently produces single-quoted strings.
+      // Single-quoted strings only accept \' and \\ escapes.
+      // https://docs.ruby-lang.org/en/2.4.0/syntax/literals_rdoc.html#label-Strings
+      charRange = "'\\\\";
+      charToEscape = {
+        "'": "\\'",
+        '\\': '\\\\',
+      };
+      toCodeEscape = (c) => c;
+      break;
+
+    default:
+      throw new RangeError(`Unrecognized language '${lang}'`);
+  }
+
+  function replaceAstral(pair) {
+    return toAstralEscape(pair.codePointAt(0));
+  }
+  function replaceChar(c) {
+    return charToEscape[c] || toCodeEscape(c);
+  }
+  const charPattern = new RegExp(`[${charRange}]`, 'g');
+  return function escapeString(str) {
+    if (!str || typeof str !== 'string') {
+      return str;
+    }
+
+    const charEscaped = str.replace(charPattern, replaceChar);
+    const astralEscaped =
+      !toAstralEscape ? charEscaped : charEscaped.replaceAll(
+        /[\uD800-\uDBFF][\uDC00-\uDFFF]/g,
+        replaceAstral,
+      );
+    return astralEscaped;
+  };
+}
+
+function escapeInSchema(schema, escapeString) {
+  const xMsEnum = schema['x-ms-enum'];
+  if (!xMsEnum || schema.type !== 'string') {
+    // Schema won't generate a class/enum with string values
+    return schema;
+  }
+
+  const xMsEnumValues = xMsEnum.values;
+  if (xMsEnumValues) {
+    // generator uses .x-ms-enum.values instead of .enum
+    return {
+      ...schema,
+      'x-ms-enum': {
+        ...xMsEnum,
+        values: xMsEnumValues.map((xMsEnumValue) => ({
+          ...xMsEnumValue,
+          value: escapeString(xMsEnumValue.value),
+        })),
+      },
+    };
+  }
+
+  return {
+    ...schema,
+    enum: schema.enum.map(escapeString),
+  };
+}
+
+/**
+ * Transformer to escape string enum values appropriately for C# string literals
+ * when code will be generated by Autorest, since it currently does not.
+ *
+ * https://github.com/Azure/autorest/issues/3371
+ */
+export default class EscapeEnumValuesTransformer
+  extends OpenApiTransformerBase {
+  constructor({ language }) {
+    super();
+
+    const typeofLanguage = typeof language;
+    switch (typeofLanguage) {
+      case 'string':
+        this[escapeStringSymbol] = makeEscapeString(language);
+        break;
+      case 'function':
+        this[escapeStringSymbol] = language;
+        break;
+      default:
+        throw new TypeError(
+          `options.language must be a string or function, got ${
+            typeofLanguage}`,
+        );
+    }
+  }
+
+  transformSchema(schema) {
+    return escapeInSchema(
+      super.transformSchema(schema),
+      this[escapeStringSymbol],
+    );
+  }
+
+  transformParameter(parameter) {
+    return escapeInSchema(
+      super.transformParameter(parameter),
+      this[escapeStringSymbol],
+    );
+  }
+}