@kevinoid/openapi-transformers 0.1.0

package/server-vars-to-path-params.js

@@ -0,0 +1,224 @@
+/**
+ * @copyright Copyright 2019-2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/server-vars-to-path-params.js"
+ */
+
+import assert from 'node:assert';
+
+// 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';
+
+/** Gets the longest common suffix of two strings.
+ *
+ * @private
+ */
+function commonSuffix(s1, s2) {
+  let i = s1.length - 1;
+  for (let j = s2.length - 1; i >= 0 && j >= 0; i -= 1, j -= 1) {
+    if (s1[i] !== s2[j]) {
+      break;
+    }
+  }
+
+  return s1.slice(i + 1);
+}
+
+/** Get the path portion of a templated URL.
+ *
+ * @private
+ */
+function getPath(url) {
+  // Note: url may be relative and lack scheme+authority
+  // Note: Can't use new URL() due to [/?#] in variable names
+  return url
+    // Remove scheme+authority, if present
+    .replace(/^(?:\{[^{}]*\}|[a-zA-Z_+.-])+:\/\/(?:\{[^{}]*\}|[^/{}])+/, '')
+    // Remove query or fragment, if present
+    .replace(/^((?:\{[^{}]*\}|[^{}?#])*)[?#].*$/, '$1');
+}
+
+/** Gets the common path segment suffix of the path part of all server URLs,
+ * containing at least one template expression.
+ *
+ * @private
+ */
+function getCommonPathSuffix(servers) {
+  // Common suffix of path part of URLs (may be in middle of template expr)
+  const commonUrlSuffix = servers
+    .map((server) => getPath(server.url))
+    .reduce(commonSuffix);
+
+  // Smallest suffix of commonUrlSuffix which begins on a path segment
+  // (i.e. at beginning or after a slash) and includes all template exprs.
+  const match = /(?:^|\/)[^/]*(?:\{[^{}]*\}[^{}]*)+$/.exec(commonUrlSuffix);
+  return match ? match[0] : '';
+}
+
+function transformPaths(paths, serverPath, serverParams) {
+  return Object.keys(paths)
+    .reduce((newPaths, path) => {
+      const pathItem = paths[path];
+      const { parameters } = pathItem;
+      newPaths[serverPath + path] = {
+        parameters:
+          parameters ? [...serverParams, ...parameters] : serverParams,
+        ...pathItem,
+      };
+      return newPaths;
+    }, Object.create(Object.getPrototypeOf(paths)));
+}
+
+/**
+ * Transformer to convert Server Variables in path portion to Parameters on
+ * Path Item Objects for use with OpenAPI 2.
+ *
+ * TODO: Roll this into OpenAPI 3 -> 2 conversion?
+ */
+export default class ServerVarsToPathParamsTransformer
+  extends OpenApiTransformerBase {
+  constructor({ omitDefault } = {}) {
+    super();
+
+    if (omitDefault !== undefined && !Array.isArray(omitDefault)) {
+      throw new TypeError('options.omitDefault must be an Array');
+    }
+
+    this.options = {
+      omitDefault: omitDefault || [],
+    };
+  }
+
+  transformOpenApi(spec) {
+    if (!spec || !spec.servers || spec.servers.length === 0) {
+      return spec;
+    }
+
+    const pathSuffix = getCommonPathSuffix(spec.servers);
+    if (!pathSuffix) {
+      return spec;
+    }
+
+    const pathSuffixVarNames = pathSuffix
+      .match(/\{[^{}]*\}/g)
+      .map((templateExpr) => templateExpr.slice(1, -1));
+
+    // Transform servers and get variables for common path suffix
+    let pathSuffixVars;
+    const newServers = spec.servers.map((server) => {
+      const newUrl = server.url.replace(pathSuffix, '');
+
+      // Separate path suffix variables from remaining server variables
+      const variables = server.variables || {};
+      let haveNewVars = false;
+      const newVars = {};
+      const suffixVars = {};
+      for (const varName of Object.keys(variables)) {
+        const variable = variables[varName];
+        if (pathSuffixVarNames.includes(varName)) {
+          // Variable in path suffix
+          if (this.options.omitDefault.includes(varName)
+            && Object.hasOwn(variable, 'default')) {
+            const newVariable = { ...variable };
+            delete newVariable.default;
+            suffixVars[varName] = newVariable;
+          } else {
+            suffixVars[varName] = variable;
+          }
+
+          // Check if variable is also in remaining server URL
+          if (newUrl.includes(`{${varName}}`)) {
+            haveNewVars = true;
+            newVars[varName] = variable;
+          }
+        } else {
+          haveNewVars = true;
+          newVars[varName] = variable;
+        }
+      }
+
+      if (pathSuffixVars === undefined) {
+        pathSuffixVars = suffixVars;
+      } else {
+        assert.deepStrictEqual(
+          pathSuffixVars,
+          suffixVars,
+          'shared path variables must be the same in all servers',
+        );
+      }
+
+      const newServer = { ...server, url: newUrl };
+
+      if (haveNewVars) {
+        newServer.variables = newVars;
+      } else {
+        delete newServer.variables;
+      }
+
+      return newServer;
+    });
+
+    // Note: Autorest treats parameters defined globally as properties of the
+    // client, rather than the method, by default (which is what we want here).
+    // https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-parameter-location
+    let parameters, paramRefPrefix;
+    if (spec.openapi) {
+      parameters = { ...spec.components && spec.components.parameters };
+      paramRefPrefix = ['components', 'parameters'];
+    } else {
+      parameters = { ...spec.parameters };
+      paramRefPrefix = ['parameters'];
+    }
+    const paramManager = new MatchingParameterManager(parameters);
+
+    const serverParamRefs = Object.keys(pathSuffixVars).map((name) => {
+      const serverVar = pathSuffixVars[name];
+      const serverParam = {
+        name,
+        in: 'path',
+        required: true,
+      };
+      if (spec.openapi) {
+        serverParam.schema = {
+          type: 'string',
+          ...serverVar,
+        };
+
+        if (Object.hasOwn(serverVar, 'description')) {
+          serverParam.description = serverVar.description;
+          delete serverParam.schema.description;
+        }
+      } else {
+        serverParam.type = 'string';
+        Object.assign(serverParam, serverVar);
+      }
+
+      const defName = paramManager.add(serverParam, name);
+      return {
+        $ref: encodeUriFragmentIdentifier([...paramRefPrefix, defName]),
+      };
+    });
+
+    const newPathPrefix = pathSuffix.replace(/\/$/, '');
+    const newSpec = {
+      ...spec,
+      servers: newServers,
+      paths: transformPaths(spec.paths, newPathPrefix, serverParamRefs),
+    };
+
+    if (spec.openapi) {
+      newSpec.components = {
+        ...spec.components,
+        parameters,
+      };
+    } else {
+      newSpec.parameters = parameters;
+    }
+
+    return newSpec;
+  }
+}

package/server-vars-to-x-ms-parameterized-host.js

@@ -0,0 +1,247 @@
+/**
+ * @copyright Copyright 2019-2020 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/server-vars-to-x-ms-parameterized-host.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+import visit from 'openapi-transformer-base/visit.js';
+
+/** Gets the scheme and authority portions of a URL template.
+ *
+ * @private
+ */
+function getSchemeAuthority(url) {
+  // Note: parameterized host may contain host and/or schema parameters.
+  // A single parameter may contain both schema and host.
+  // No way to disambiguate url like {schema}{host}{pathPrefix}.
+  // Assume the scheme+authority parts end at first slash following //
+  // (if present).  (Note: protocol-relative url may start with //)
+  const match =
+    /^(?:(?:\{[^{}]*\}|[^/{}])*\/\/)?(?:\{[^{}]*\}|[^/{}])+/.exec(url);
+  return match && match[0];
+}
+
+function parseServerUrl(url) {
+  if (typeof url !== 'string') {
+    this.warn('Ignoring Server with non-string url', url);
+    return undefined;
+  }
+
+  const schemeAuth = getSchemeAuthority(url);
+  if (!schemeAuth) {
+    this.warn('Unable to determine scheme and authority for url', url);
+    return undefined;
+  }
+
+  // Remove non-templated scheme, if present
+  const hostTemplate = schemeAuth.replace(/^[a-zA-Z_+.-]+:\/\//, '');
+  if (!hostTemplate) {
+    this.warn('Unable to determine host for url', url);
+    return undefined;
+  }
+
+  const hostTemplateExprs = hostTemplate.match(/\{[^{}]*\}/g);
+  if (!hostTemplateExprs) {
+    this.warn('No template expressions in scheme and authority for url', url);
+    return undefined;
+  }
+
+  return {
+    hostTemplate,
+    // If non-templated scheme was removed, use the declared schemes
+    useSchemePrefix: hostTemplate !== schemeAuth,
+    hostTemplateVarNames: hostTemplateExprs
+      .map((templateExpr) => templateExpr.slice(1, -1)),
+  };
+}
+
+/**
+ * Transformer to convert Server Variables in host portion to
+ * x-ms-parameterized-host for use with OpenAPI 2.
+ *
+ * https://github.com/Azure/autorest/tree/main/docs/extensions#x-ms-parameterized-host
+ *
+ * TODO: Roll this into OpenAPI 3 -> 2 conversion?
+ *
+ * Note: Currently expects OAS3 input (required for Server Objects) but
+ * produces OAS2 parameters as specified for x-ms-parameterized-host.
+ */
+export default class ServerVarsToParamHostTransformer
+  extends OpenApiTransformerBase {
+  constructor({ omitDefault, parameter, xMsParameterizedHost } = {}) {
+    super();
+
+    if (omitDefault !== undefined && !Array.isArray(omitDefault)) {
+      throw new TypeError('options.omitDefault must be an Array');
+    }
+
+    if (parameter !== undefined
+      && (parameter === null
+        || typeof parameter !== 'object')) {
+      throw new TypeError('options.parameter must be a object');
+    }
+
+    if (xMsParameterizedHost !== undefined
+      && (xMsParameterizedHost === null
+        || typeof xMsParameterizedHost !== 'object')) {
+      throw new TypeError('options.xMsParameterizedHost must be a object');
+    }
+
+    this.options = {
+      omitDefault: omitDefault || [],
+      parameter,
+      xMsParameterizedHost,
+    };
+  }
+
+  transformServerVariableToParameter(serverVariable) {
+    if (serverVariable === null
+      || typeof serverVariable !== 'object'
+      || Array.isArray(serverVariable)) {
+      this.warn('Ignoring non-object Server Variable', serverVariable);
+      return undefined;
+    }
+
+    return {
+      name: undefined,
+      type: 'string',
+      ...serverVariable,
+      in: 'path',
+      required: true,
+      ...this.options.parameter,
+    };
+  }
+
+  transformServerVariablesToParameters(variables, varNames) {
+    if (variables === null
+      || typeof variables !== 'object'
+      || Array.isArray(variables)) {
+      this.warn('Ignoring non-object Map', variables);
+      return undefined;
+    }
+
+    const parameters = [];
+    for (const varName of varNames) {
+      const variable =
+        Object.hasOwn(variables, varName) ? variables[varName]
+          : undefined;
+      if (variable === undefined) {
+        this.warn('Unable to convert Server missing variable %j', varName);
+        return undefined;
+      }
+
+      const parameter = visit(
+        this,
+        this.transformServerVariableToParameter,
+        varName,
+        variable,
+      );
+      if (!parameter) {
+        return undefined;
+      }
+
+      parameter.name = varName;
+
+      if (this.options.omitDefault.includes(varName)
+        && Object.hasOwn(parameter, 'default')) {
+        delete parameter.default;
+      }
+
+      parameters.push(parameter);
+    }
+
+    return parameters;
+  }
+
+  transformServerToParameterizedHost(server) {
+    if (server === null
+      || typeof server !== 'object'
+      || Array.isArray(server)) {
+      this.warn('Ignoring non-object Server', server);
+      return undefined;
+    }
+
+    const { url, variables = {} } = server;
+
+    const urlParts = visit(this, parseServerUrl, 'url', url);
+    if (!urlParts) {
+      return undefined;
+    }
+
+    const {
+      hostTemplate,
+      useSchemePrefix,
+      hostTemplateVarNames,
+    } = urlParts;
+
+    const parameters = visit(
+      this,
+      this.transformServerVariablesToParameters,
+      'variables',
+      variables,
+      hostTemplateVarNames,
+    );
+    if (!parameters) {
+      return undefined;
+    }
+
+    return {
+      hostTemplate,
+      useSchemePrefix,
+      parameters,
+      ...this.options.xMsParameterizedHost,
+    };
+  }
+
+  transformServersToParameterizedHost(servers) {
+    if (!Array.isArray(servers)) {
+      this.warn('Ignoring non-Array servers', servers);
+      return undefined;
+    }
+
+    if (servers.length === 0) {
+      this.warn('Ignoring empty servers', servers);
+      return undefined;
+    }
+
+    if (servers.length > 1) {
+      this.warn('Ignoring all but first server', servers);
+    }
+
+    return visit(
+      this,
+      this.transformServerToParameterizedHost,
+      '0',
+      servers[0],
+    );
+  }
+
+  transformOpenApi(openApi) {
+    if (openApi === null
+      || typeof openApi !== 'object'
+      || Array.isArray(openApi)) {
+      this.warn('Ignoring non-object OpenAPI', openApi);
+      return openApi;
+    }
+
+    if (openApi.servers === undefined) {
+      return openApi;
+    }
+
+    const parameterizedHost = visit(
+      this,
+      this.transformServersToParameterizedHost,
+      'servers',
+      openApi.servers,
+    );
+    if (parameterizedHost === undefined) {
+      return openApi;
+    }
+
+    return {
+      ...openApi,
+      'x-ms-parameterized-host': parameterizedHost,
+    };
+  }
+}

package/type-null-to-enum.js

@@ -0,0 +1,47 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/type-null-to-enum.js"
+ */
+
+import { isDeepStrictEqual } from 'node:util';
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to convert Schema Objects with `type: 'null'` (as in OAS 3.1 and
+ * JSON Schema) to `enum: [null]` for OAS 3.0 and 2.0.
+ */
+export default class TypeNullToEnumTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (newSchema === null
+      || typeof newSchema !== 'object'
+      || Array.isArray(newSchema)) {
+      return newSchema;
+    }
+
+    const { type } = newSchema;
+    if (type === 'null'
+      || (Array.isArray(type)
+        && type.length > 0
+        && type.every((t) => t === 'null'))) {
+      const { type: _, ...schemaNoType } = newSchema;
+      if (schemaNoType.enum === undefined) {
+        // eslint-disable-next-line unicorn/no-null
+        schemaNoType.enum = [null];
+      // eslint-disable-next-line unicorn/no-null
+      } else if (!isDeepStrictEqual(schemaNoType.enum, [null])) {
+        this.warn(
+          'refusing to overwrite enum of schema with type: null',
+          newSchema,
+        );
+      }
+
+      return schemaNoType;
+    }
+
+    return newSchema;
+  }
+}

package/type-null-to-nullable.js

@@ -0,0 +1,57 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/type-null-to-nullable.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to convert Schema Objects with `'null'` in `type` (as in OAS
+ * 3.1 and JSON Schema) to `nullable: true`.
+ */
+export default class TypeNullToNullableTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (newSchema === null
+      || typeof newSchema !== 'object'
+      || Array.isArray(newSchema)) {
+      return newSchema;
+    }
+
+    const { type } = newSchema;
+    if (!Array.isArray(type)) {
+      // Can't remove 'null' from non-Array type
+      // Note: See null-type-to-enum for handling `type: 'null'`
+      return newSchema;
+    }
+
+    const newType = type.filter((t) => t !== 'null');
+    if (newType.length === type.length) {
+      // type does not contain 'null'
+      return newSchema;
+    }
+
+    if (newType.length === 0) {
+      // Can't handle type with only 'null'
+      // Note: See null-type-to-enum for handling `type: 'null'`
+      return newSchema;
+    }
+
+    const { nullable } = newSchema;
+    if (nullable !== undefined && nullable !== true) {
+      this.warn(
+        'schema with nullable: %o and type: null!?',
+        nullable,
+        newSchema,
+      );
+    }
+
+    return {
+      ...newSchema,
+      type: newType.length === 1 ? newType[0] : newType,
+      nullable: nullable === undefined ? true : nullable,
+    };
+  }
+}