@kevinoid/openapi-transformers 0.1.0

package/remove-response-headers.js

@@ -0,0 +1,42 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/remove-response-headers.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to remove headers from Response objects in an OpenAPI 3 doc.
+ *
+ * This can be useful because Autorest generates strongly typed classes for
+ * each response type, which can be an annoyance (especially if the default
+ * error response has headers), particularly since x-ms-headers is not working
+ * correctly: https://github.com/Azure/autorest/pull/3322
+ */
+export default class RemoveResponseHeadersTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformResponse(response) {
+    if (response.headers) {
+      const newResponse = { ...response };
+      delete newResponse.headers;
+      return newResponse;
+    }
+
+    return response;
+  }
+
+  // Optimization: Only need to transform responses
+  transformComponents(components) {
+    if (components.responses) {
+      return {
+        ...components,
+        responses:
+          this.transformMap(components.responses, this.transformResponse),
+      };
+    }
+
+    return components;
+  }
+}

package/remove-security-scheme-if.js

@@ -0,0 +1,166 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const emptyRequirement = {};
+const predicateSymbol = Symbol('predicate');
+const removedSchemesSymbol = Symbol('removedSchemes');
+
+/**
+ * Transformer to remove security schemes matching a given predicate.
+ */
+export default class RemoveSecuritySchemeIfTransformer
+  extends OpenApiTransformerBase {
+  /** Constructs a new RemoveSecuritySchemeIfTransformer with a given
+   * predicate.
+   *
+   * @param {function(!object)} predicate Predicate which returns true if
+   * the given Security Scheme should be removed and false otherwise.
+   */
+  constructor(predicate) {
+    if (typeof predicate !== 'function') {
+      throw new TypeError('predicate must be a function');
+    }
+
+    super();
+
+    this[predicateSymbol] = predicate;
+    this[removedSchemesSymbol] = new Set();
+  }
+
+  transformSecuritySchemesEarly(securitySchemes) {
+    const removedSchemes = this[removedSchemesSymbol];
+
+    let isEmpty = true;
+    const newSecuritySchemes = {};
+    for (const [schemeName, securityScheme]
+      of Object.entries(securitySchemes)) {
+      if (securityScheme !== undefined) {
+        if (this[predicateSymbol](securityScheme)) {
+          removedSchemes.add(schemeName);
+        } else {
+          isEmpty = false;
+          newSecuritySchemes[schemeName] = securityScheme;
+        }
+      }
+    }
+
+    return isEmpty ? undefined : newSecuritySchemes;
+  }
+
+  transformSecurityRequirement(securityRequirement) {
+    if (typeof securityRequirement !== 'object'
+      || securityRequirement === null) {
+      this.warn(
+        'Ignoring non-object Security Requirement',
+        securityRequirement,
+      );
+      return securityRequirement;
+    }
+
+    if (Array.isArray(securityRequirement)) {
+      this.warn(
+        'Ignoring non-object Security Requirement',
+        securityRequirement,
+      );
+      return securityRequirement;
+    }
+
+    const removedSchemes = this[removedSchemesSymbol];
+    let isEmpty = true;
+    let removedAny = false;
+    const newSecurityRequirement = {};
+    for (const [schemeName, securityScheme]
+      of Object.entries(securityRequirement)) {
+      if (securityScheme !== undefined) {
+        if (removedSchemes.has(schemeName)) {
+          removedAny = true;
+        } else {
+          isEmpty = false;
+          newSecurityRequirement[schemeName] = securityScheme;
+        }
+      }
+    }
+
+    // Return empty marker only if it was made empty by removing scheme(s).
+    // Leave already (effectively) empty Security Requirements as-is.
+    return removedAny && isEmpty ? emptyRequirement : newSecurityRequirement;
+  }
+
+  transformOperation(operation) {
+    const newOperation = super.transformOperation(operation);
+
+    if (newOperation
+      && Array.isArray(newOperation.security)
+      && newOperation.security.length > 0) {
+      // Remove any empty requirements which were created.
+      newOperation.security =
+        newOperation.security.filter((sr) => sr !== emptyRequirement);
+
+      // Remove the whole array if there are no requirements remaining.
+      if (newOperation.security.length === 0) {
+        delete newOperation.security;
+      }
+    }
+
+    return newOperation;
+  }
+
+  transformOpenApi(openApi) {
+    let newSecuritySchemes;
+    if (openApi
+      && openApi.components
+      && openApi.components.securitySchemes) {
+      newSecuritySchemes =
+        this.transformSecuritySchemesEarly(openApi.components.securitySchemes);
+    }
+
+    let newSecurityDefinitions;
+    if (openApi && openApi.securityDefinitions) {
+      newSecurityDefinitions =
+        this.transformSecuritySchemesEarly(openApi.securityDefinitions);
+    }
+
+    if (this[removedSchemesSymbol].size === 0) {
+      return openApi;
+    }
+
+    let newOpenApi = super.transformOpenApi(openApi);
+    if (newOpenApi === openApi) {
+      newOpenApi = { ...newOpenApi };
+    }
+
+    if (Array.isArray(newOpenApi.security)
+      && newOpenApi.security.length > 0) {
+      // Remove any empty requirements which were created.
+      newOpenApi.security =
+        newOpenApi.security.filter((sr) => sr !== emptyRequirement);
+
+      // Remove the whole array if there are no requirements remaining.
+      if (newOpenApi.security.length === 0) {
+        delete newOpenApi.security;
+      }
+    }
+
+    // Remove securitySchemes where appropriate
+    if (newOpenApi.components) {
+      if (newSecuritySchemes === undefined) {
+        delete newOpenApi.components.securitySchemes;
+      } else {
+        newOpenApi.components.securitySchemes = newSecuritySchemes;
+      }
+    }
+
+    // Remove securityDefinitions where appropriate
+    if (newSecurityDefinitions === undefined) {
+      delete newOpenApi.securityDefinitions;
+    } else {
+      newOpenApi.securityDefinitions = newSecurityDefinitions;
+    }
+
+    return newOpenApi;
+  }
+}

package/remove-type-if.js

@@ -0,0 +1,65 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/remove-type-if.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const predicateSymbol = Symbol('predicate');
+
+/** Checks if a given type constraint validates all types other than null.
+ *
+ * The type constraint may or may not include null.
+ *
+ * This predicate is useful for conversion of schemas which explicitly accept
+ * any type (and are only valid in OAS 3.1 and JSON Schema) to implicitly
+ * accept any type (which are valid in all OAS and JSON Schema versions).
+ * "null" is excluded because it must be handled by `nullable` in OAS 3
+ * (and `x-nullable` in OAS 2).
+ *
+ * @param {string|!Array<string>} type Schema Object type.
+ * @returns {boolean} true if type is an Array which contains the 5 JSON
+ * Schema types other than "null" (handled by `nullable`) and "integer"
+ * (covered by "number"), which may or may not be present.  Otherwise false.
+ */
+export function allNonNullTypes(type) {
+  return Array.isArray(type)
+    && type.length >= 5
+    && [
+      'array',
+      'boolean',
+      'number',
+      'object',
+      'string',
+    ].every((t) => type.includes(t));
+}
+
+/**
+ * Transformer to remove `type` from Schema Objects where `type` matches a
+ * given predicate.
+ */
+export default class RemoveTypeIfTransformer extends OpenApiTransformerBase {
+  constructor(predicate) {
+    super();
+
+    if (typeof predicate !== 'function') {
+      throw new TypeError('predicate must be a function');
+    }
+
+    this[predicateSymbol] = predicate;
+  }
+
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (newSchema === null
+      || typeof newSchema !== 'object'
+      || Array.isArray(newSchema)
+      || newSchema.type === undefined) {
+      return newSchema;
+    }
+
+    const { type, ...schemaNoType } = newSchema;
+    return this[predicateSymbol](type) ? schemaNoType : newSchema;
+  }
+}

package/rename-components.js

@@ -0,0 +1,285 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/rename-components.js"
+ */
+
+// Note: Undocumented functions which are part of the public API:
+// https://github.com/flitbit/json-ptr/issues/29
+import {
+  decodeUriFragmentIdentifier,
+  encodeUriFragmentIdentifier,
+} from 'json-ptr';
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const renameFuncsSymbol = Symbol('renameFuncs');
+
+// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields-6
+const componentFieldNames = [
+  'schemas',
+  'responses',
+  'parameters',
+  'examples',
+  'requestBodies',
+  'headers',
+  'securitySchemes',
+  'links',
+  'callbacks',
+  'pathItems',
+];
+
+function renameProps(obj, renameFunc) {
+  if (!renameFunc
+    || typeof obj !== 'object'
+    || obj === null
+    || Array.isArray(obj)) {
+    return obj;
+  }
+
+  const newObj = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = renameFunc(key);
+    if (Object.hasOwn(newObj, newKey)) {
+      throw new Error(
+        `New name ${newKey} for ${key} conflicts with existing name`,
+      );
+    }
+    newObj[newKey] = value;
+  }
+
+  return newObj;
+}
+
+function isJsonRef(obj) {
+  return obj && typeof obj.$ref === 'string';
+}
+
+function renameRefObj(obj, getPathIndex, renameFunc) {
+  if (!renameFunc) {
+    return obj;
+  }
+
+  const { $ref } = obj;
+  if ($ref[0] !== '#') {
+    return obj;
+  }
+
+  let tokens;
+  try {
+    tokens = decodeUriFragmentIdentifier($ref);
+  } catch {
+    return obj;
+  }
+
+  const renameInd = getPathIndex(tokens);
+  if (renameInd < 0 || renameInd >= tokens.length) {
+    return obj;
+  }
+
+  const name = tokens[renameInd];
+  const newName = renameFunc(name);
+  if (newName !== name) {
+    tokens[renameInd] = newName;
+    return {
+      ...obj,
+      $ref: encodeUriFragmentIdentifier(tokens),
+    };
+  }
+
+  return obj;
+}
+
+/**
+ * Transformer to rename components.
+ */
+export default class RenameComponentsTransformer
+  extends OpenApiTransformerBase {
+  constructor(options) {
+    super();
+
+    if (typeof options !== 'object' || options === null) {
+      throw new TypeError('options must be an object');
+    }
+
+    const renameFuncs = {};
+    for (const componentFieldName of componentFieldNames) {
+      const renameFuncOrMap = options[componentFieldName];
+      if (typeof renameFuncOrMap === 'function') {
+        renameFuncs[componentFieldName] = renameFuncOrMap;
+      } else if (typeof renameFuncOrMap === 'object') {
+        const patterns = Object.entries(renameFuncOrMap)
+          .map(([k, v]) => [new RegExp(k, 'g'), v]);
+        renameFuncs[componentFieldName] = (name) => {
+          for (const [pat, repl] of patterns) {
+            if (pat.test(name)) {
+              return name.replace(pat, repl);
+            }
+          }
+          return name;
+        };
+      } else if (renameFuncOrMap !== undefined) {
+        throw new TypeError(`options.${componentFieldName} must be a function`);
+      }
+    }
+
+    this[renameFuncsSymbol] = renameFuncs;
+  }
+
+  transformExample3(example) {
+    if (isJsonRef(example)) {
+      return renameRefObj(
+        example,
+        (pp) => (pp[0] === 'components' && pp[1] === 'examples' ? 2 : -1),
+        this[renameFuncsSymbol].examples,
+      );
+    }
+
+    return super.transformExample3(example);
+  }
+
+  transformSchema(schema) {
+    if (isJsonRef(schema)) {
+      return renameRefObj(
+        schema,
+        (pp) => (pp[0] === 'components' && pp[1] === 'schemas' ? 2
+          : pp[0] === 'definitions' ? 1 : -1),
+        this[renameFuncsSymbol].schemas,
+      );
+    }
+
+    return super.transformSchema(schema);
+  }
+
+  transformHeader(header) {
+    if (isJsonRef(header)) {
+      return renameRefObj(
+        header,
+        (pp) => (pp[0] === 'components' && pp[1] === 'headers' ? 2 : -1),
+        this[renameFuncsSymbol].headers,
+      );
+    }
+
+    return super.transformHeader(header);
+  }
+
+  transformLink(link) {
+    if (isJsonRef(link)) {
+      return renameRefObj(
+        link,
+        (pp) => (pp[0] === 'components' && pp[1] === 'links' ? 2 : -1),
+        this[renameFuncsSymbol].links,
+      );
+    }
+
+    return super.transformLink(link);
+  }
+
+  transformResponse(response) {
+    if (isJsonRef(response)) {
+      return renameRefObj(
+        response,
+        (pp) => (pp[0] === 'components' && pp[1] === 'responses' ? 2 : -1),
+        this[renameFuncsSymbol].responses,
+      );
+    }
+
+    return super.transformResponse(response);
+  }
+
+  transformParameter(parameter) {
+    if (isJsonRef(parameter)) {
+      return renameRefObj(
+        parameter,
+        (pp) => (pp[0] === 'components' && pp[1] === 'parameters' ? 2 : -1),
+        this[renameFuncsSymbol].parameters,
+      );
+    }
+
+    return super.transformParameter(parameter);
+  }
+
+  transformCallback(callback) {
+    if (isJsonRef(callback)) {
+      return renameRefObj(
+        callback,
+        (pp) => (pp[0] === 'components' && pp[1] === 'callbacks' ? 2 : -1),
+        this[renameFuncsSymbol].callbacks,
+      );
+    }
+
+    return super.transformCallback(callback);
+  }
+
+  transformRequestBody(requestBody) {
+    if (isJsonRef(requestBody)) {
+      return renameRefObj(
+        requestBody,
+        (pp) => (pp[0] === 'components' && pp[1] === 'requestBodies' ? 2 : -1),
+        this[renameFuncsSymbol].requestBodies,
+      );
+    }
+
+    return super.transformRequestBody(requestBody);
+  }
+
+  transformSecurityRequirement(securityRequirement) {
+    return renameProps(
+      super.transformSecurityRequirement(securityRequirement),
+      this[renameFuncsSymbol].securitySchemes,
+    );
+  }
+
+  transformPathItem(pathItem) {
+    if (isJsonRef(pathItem)) {
+      return renameRefObj(
+        pathItem,
+        (pp) => (pp[0] === 'components' && pp[1] === 'pathItems' ? 2 : -1),
+        this[renameFuncsSymbol].pathItems,
+      );
+    }
+
+    return super.transformPathItem(pathItem);
+  }
+
+  transformComponents(components) {
+    components = super.transformComponents(components);
+
+    if (typeof components !== 'object'
+      || components === null
+      || Array.isArray(components)) {
+      return components;
+    }
+
+    const newComponents = { ...components };
+    for (const [propName, renameFunc]
+      of Object.entries(this[renameFuncsSymbol])) {
+      const propValue = components[propName];
+      if (propValue) {
+        newComponents[propName] = renameProps(propValue, renameFunc);
+      }
+    }
+
+    return newComponents;
+  }
+
+  transformOpenApi(openApi) {
+    openApi = super.transformOpenApi(openApi);
+
+    if (typeof openApi !== 'object'
+      || openApi === null
+      || Array.isArray(openApi)) {
+      return openApi;
+    }
+
+    const { definitions } = openApi;
+    const renameSchemas = this[renameFuncsSymbol].schemas;
+    if (definitions && renameSchemas) {
+      openApi = {
+        ...openApi,
+        definitions: renameProps(definitions, renameSchemas),
+      };
+    }
+
+    return openApi;
+  }
+}

package/replaced-by-to-description.js

@@ -0,0 +1,50 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/replaced-by-to-description.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+function transformXDeprecated(schema) {
+  const xDeprecated = schema['x-deprecated'];
+  if (xDeprecated
+    && !Object.hasOwn(xDeprecated, 'description')
+    && Object.hasOwn(xDeprecated, 'replaced-by')) {
+    return {
+      ...schema,
+      'x-deprecated': {
+        description: `Use ${xDeprecated['replaced-by']} instead.`,
+        ...xDeprecated,
+      },
+    };
+  }
+
+  return schema;
+}
+
+/**
+ * Transformer to convert x-deprecated.replaced-by to x-deprecated.description,
+ * if not present.
+ * https://github.com/Azure/autorest/tree/master/Samples/test/deprecated
+ *
+ * Since Autorest C# doesn't use replaced-by, but does use description.
+ */
+export default class ReplacedByToDescriptionTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    return transformXDeprecated(super.transformSchema(schema));
+  }
+
+  transformParameter(parameter) {
+    return transformXDeprecated(super.transformParameter(parameter));
+  }
+
+  transformHeader(header) {
+    return transformXDeprecated(super.transformHeader(header));
+  }
+
+  transformOperation(operation) {
+    return transformXDeprecated(super.transformOperation(operation));
+  }
+}