@kevinoid/openapi-transformers 0.1.0

package/nullable-not-required.js

@@ -0,0 +1,240 @@
+/**
+ * @copyright Copyright 2019-2024 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/nullable-not-required.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Determines whether a given Schema can have a null value.
+ *
+ * @param {!object} schema OpenAPI Schema object.
+ * @param {boolean} hasNullType Whether 'null' is a valid Schema type.
+ * @param {boolean} refNullable Treat $ref as nullable.
+ * @returns {boolean} <c>true</c> if <c>null</c> is a valid value for
+ * <c>schema</c>.
+ */
+function isNullable(schema, hasNullType, refNullable) {
+  const {
+    $ref,
+    nullable,
+    'x-nullable': xNullable,
+    type,
+  } = schema;
+
+  if ($ref) {
+    if (typeof nullable === 'boolean') {
+      return nullable;
+    }
+
+    if (typeof xNullable === 'boolean') {
+      return xNullable;
+    }
+
+    return refNullable;
+  }
+
+  if (hasNullType) {
+    if (typeof type === 'string') {
+      if (type !== 'null') {
+        // null forbidden by non-null type
+        return false;
+      }
+    } else if (Array.isArray(type)
+      && !type.includes('null')) {
+      // null forbidden by null not in types
+      return false;
+    }
+  } else if (!nullable && !xNullable) {
+    // Without null type, null is only allowed with nullable (or x-nullable)
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Determines whether a given property of a given schema can have a null value.
+ *
+ * @param {!object} schema OpenAPI Schema object.
+ * @param {string} propName Name of property to check.
+ * @param {boolean} hasNullType Whether 'null' is a valid Schema type.
+ * @param {boolean} refNullable Treat $ref as nullable.
+ * @returns {?boolean} <c>true</c> if <c>null</c> is known to be a valid value
+ * for <c>propName</c> in <c>schema</c>, <c>false</c> if <c>null</c> is known
+ * to be an invalid value for <c>propName</c> in <c>schema</c>.
+ * <c>undefined</c> if <c>propName</c> is not constrained by <c>schema</c>.
+ */
+function isPropNullable(schema, propName, hasNullType, refNullable) {
+  const {
+    additionalProperties,
+    allOf,
+    anyOf,
+    oneOf,
+    properties,
+  } = schema;
+  let constrained = false;
+  const propSchema = properties?.[propName];
+  if (propSchema) {
+    constrained = true;
+    if (!isNullable(propSchema, hasNullType, refNullable)) {
+      return false;
+    }
+  } else if (additionalProperties) {
+    constrained = true;
+    if (!isNullable(additionalProperties, hasNullType, refNullable)) {
+      // schema in additionalProperties does not allow null
+      return false;
+    }
+  } else if (additionalProperties === false) {
+    // would fail validation if property is present
+    return false;
+  }
+
+  if (Array.isArray(allOf)) {
+    for (const allSchema of allOf) {
+      switch (isPropNullable(allSchema, propName, hasNullType, refNullable)) {
+        case false:
+          // If an allOf schema doesn't allow null, it's not allowed.
+          return false;
+
+        case true:
+          // An allOf schema allows null
+          constrained = true;
+          break;
+
+        default:
+          // An allOf schema doesn't constrain propName
+          break;
+      }
+    }
+  }
+
+  if (Array.isArray(anyOf)) {
+    let anyNullable = false;
+    let anyUnconstrained = false;
+    for (const anySchema of anyOf) {
+      switch (isPropNullable(anySchema, propName, hasNullType, refNullable)) {
+        case false:
+          // An anyOf schema disallows null
+          break;
+
+        case true:
+          // An anyOf schema allows null
+          anyNullable = true;
+          break;
+
+        default:
+          // An anyOf schema doesn't constrain propName
+          anyUnconstrained = true;
+          break;
+      }
+    }
+
+    if (!anyNullable && !anyUnconstrained) {
+      return false;
+    }
+
+    if (!anyUnconstrained) {
+      constrained = true;
+    }
+  }
+
+  if (Array.isArray(oneOf)) {
+    let anyNullable = false;
+    let anyUnconstrained = false;
+    for (const oneSchema of oneOf) {
+      switch (isPropNullable(oneSchema, propName, hasNullType, refNullable)) {
+        case false:
+          // A oneOf schema disallows null
+          break;
+
+        case true:
+          // A oneOf schema allows null
+          anyNullable = true;
+          break;
+
+        default:
+          // A oneOf schema doesn't constrain propName
+          anyUnconstrained = true;
+          break;
+      }
+    }
+
+    if (!anyNullable && !anyUnconstrained) {
+      return false;
+    }
+
+    if (!anyUnconstrained) {
+      constrained = true;
+    }
+  }
+
+  return constrained ? true : undefined;
+}
+
+/**
+ * Transformer to make properties which are nullable non-required to work around
+ * partial support for x-nullable in Autorest.  Currently nullable data types
+ * are used (e.g. Nullable<int>) but the Validate() method doesn't allow null.
+ * See:  https://github.com/Azure/autorest/issues/3300
+ */
+export default class NullableNotRequiredTransformer
+  extends OpenApiTransformerBase {
+  hasNullType = undefined;
+
+  refNullable = false;
+
+  requireUnconstrained = false;
+
+  constructor(options) {
+    super();
+    this.refNullable = Boolean(options?.refNullable);
+    this.requireUnconstrained = Boolean(options?.requireUnconstrained);
+  }
+
+  transformSchema(schema) {
+    const newSchema = super.transformSchema(schema);
+    if (!Array.isArray(newSchema?.required)
+      || newSchema.required.length === 0) {
+      // No properties are required. None to remove.
+      return newSchema;
+    }
+
+    const transformed = {
+      ...newSchema,
+      required: newSchema.required
+        .filter(
+          (reqName) => !(isPropNullable(
+            newSchema,
+            reqName,
+            this.hasNullType,
+            this.refNullable,
+          ) ?? !this.requireUnconstrained),
+        ),
+    };
+
+    if (transformed.required.length === 0) {
+      delete transformed.required;
+    }
+
+    return transformed;
+  }
+
+  transformOpenApi(openApi) {
+    const version = openApi?.openapi || openApi?.swagger;
+    const verParts = version ? String(version).split('.').map(Number) : [];
+    if (verParts[0] > 3 || (verParts[0] === 3 && verParts[1] >= 1)) {
+      this.hasNullType = true;
+    } else if (verParts[0] < 3 || (verParts[0] === 3 && verParts[1] < 1)) {
+      this.hasNullType = false;
+    }
+
+    try {
+      return super.transformOpenApi(openApi);
+    } finally {
+      this.hasNullType = undefined;
+    }
+  }
+}

package/nullable-to-type-null.js

@@ -0,0 +1,46 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/nullable-to-type-null.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to add `'null'` to `type` of Schema Objects with
+ * `nullable: true` or `x-nullable: true`.
+ *
+ * This is useful for converting from OpenAPI 2.0/3.0 to OpenAPI 3.1 or
+ * JSON Schema.
+ */
+export default class NullableToTypeNullTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    schema = super.transformSchema(schema);
+    if (schema === null
+      || typeof schema !== 'object'
+      || Array.isArray(schema)) {
+      return schema;
+    }
+
+    const {
+      nullable,
+      'x-nullable': xNullable,
+      ...schemaNoNullable
+    } = schema;
+    if (nullable !== true && xNullable !== true) {
+      return schema;
+    }
+
+    const { type } = schema;
+    if (Array.isArray(type)) {
+      if (!type.includes('null')) {
+        schemaNoNullable.type = [...type, 'null'];
+      }
+    } else if (type !== undefined) {
+      schemaNoNullable.type = [type, 'null'];
+    }
+
+    return schemaNoNullable;
+  }
+}

package/openapi31to30.js

@@ -0,0 +1,54 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/openapi31to30.js"
+ */
+
+import AnyOfNullToNullableTransformer from './any-of-null-to-nullable.js';
+import ConstToEnumTransformer from './const-to-enum.js';
+import ExclusiveMinMaxToBoolTransformer from './exclusive-min-max-to-bool.js';
+import PatternPropertiesToAdditionalPropertiesTransformer
+  from './pattern-properties-to-additional-properties.js';
+import RemoveTypeIfTransformer, { allNonNullTypes } from './remove-type-if.js';
+import TypeNullToEnumTransformer from './type-null-to-enum.js';
+import TypeNullToNullableTransformer from './type-null-to-nullable.js';
+
+/**
+ * Transformer to convert an OpenAPI 3.1.* document to OpenAPI 3.0.3.
+ */
+export default class OpenApi31To30Transformer {
+  constructor() {
+    this.transformers = [
+      new ExclusiveMinMaxToBoolTransformer(),
+      new ConstToEnumTransformer(),
+      new AnyOfNullToNullableTransformer(),
+      new TypeNullToEnumTransformer(),
+      new TypeNullToNullableTransformer(),
+      new RemoveTypeIfTransformer(allNonNullTypes),
+      new PatternPropertiesToAdditionalPropertiesTransformer(),
+    ];
+  }
+
+  transformOpenApi(openApi) {
+    if (typeof openApi !== 'object'
+      || openApi === null
+      || Array.isArray(openApi)) {
+      this.warn('Ignoring non-object OpenAPI', openApi);
+      return openApi;
+    }
+
+    if (typeof openApi.openapi !== 'string'
+      || !openApi.openapi.startsWith('3.1.')) {
+      this.warn('Expected OpenAPI 3.1, got', openApi.openapi);
+    }
+
+    for (const transformer of this.transformers) {
+      openApi = transformer.transformOpenApi(openApi);
+    }
+
+    return {
+      ...openApi,
+      openapi: '3.0.3',
+    };
+  }
+}

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@kevinoid/openapi-transformers",
+  "version": "0.1.0",
+  "description": "A collection of classes for transforming OpenAPI documents, particularly for compatibility with code generators like Autorest and OpenAPI Generator.",
+  "keywords": [
+    "autorest",
+    "openapi",
+    "openapi-transformer",
+    "swagger"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/kevinoid/openapi-transformers",
+  "bugs": "https://github.com/kevinoid/openapi-transformers/issues",
+  "author": "Kevin Locke <kevin@kevinlocke.name>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevinoid/openapi-transformers.git"
+  },
+  "type": "module",
+  "files": [
+    "*.js",
+    "!eslint.config.js",
+    "lib/",
+    "!**/.*"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./additional-properties-to-object.js": "./additional-properties-to-object.js",
+    "./additional-properties-to-unconstrained.js": "./additional-properties-to-unconstrained.js",
+    "./add-tag-to-operation-ids.js": "./add-tag-to-operation-ids.js",
+    "./add-x-ms-enum-name.js": "./add-x-ms-enum-name.js",
+    "./add-x-ms-enum-value-names.js": "./add-x-ms-enum-value-names.js",
+    "./any-of-null-to-nullable.js": "./any-of-null-to-nullable.js",
+    "./assert-properties.js": "./assert-properties.js",
+    "./binary-string-to-file.js": "./binary-string-to-file.js",
+    "./bool-enum-to-bool.js": "./bool-enum-to-bool.js",
+    "./clear-html-response-schema.js": "./clear-html-response-schema.js",
+    "./client-params-to-global.js": "./client-params-to-global.js",
+    "./const-to-enum.js": "./const-to-enum.js",
+    "./escape-enum-values.js": "./escape-enum-values.js",
+    "./exclusive-min-max-to-bool.js": "./exclusive-min-max-to-bool.js",
+    "./format-to-type.js": "./format-to-type.js",
+    "./inline-non-object-schemas.js": "./inline-non-object-schemas.js",
+    "./merge-all-of.js": "./merge-all-of.js",
+    "./merge-any-of.js": "./merge-any-of.js",
+    "./merge-one-of.js": "./merge-one-of.js",
+    "./nullable-not-required.js": "./nullable-not-required.js",
+    "./nullable-to-type-null.js": "./nullable-to-type-null.js",
+    "./openapi31to30.js": "./openapi31to30.js",
+    "./package.json": "./package.json",
+    "./path-parameters-to-operations.js": "./path-parameters-to-operations.js",
+    "./pattern-properties-to-additional-properties.js": "./pattern-properties-to-additional-properties.js",
+    "./queries-to-x-ms-paths.js": "./queries-to-x-ms-paths.js",
+    "./read-only-not-required.js": "./read-only-not-required.js",
+    "./ref-path-parameters.js": "./ref-path-parameters.js",
+    "./remove-default-only-response-produces.js": "./remove-default-only-response-produces.js",
+    "./remove-paths-with-servers.js": "./remove-paths-with-servers.js",
+    "./remove-query-from-paths.js": "./remove-query-from-paths.js",
+    "./remove-ref-siblings.js": "./remove-ref-siblings.js",
+    "./remove-request-body.js": "./remove-request-body.js",
+    "./remove-response-headers.js": "./remove-response-headers.js",
+    "./remove-security-scheme-if.js": "./remove-security-scheme-if.js",
+    "./remove-type-if.js": "./remove-type-if.js",
+    "./rename-components.js": "./rename-components.js",
+    "./replaced-by-to-description.js": "./replaced-by-to-description.js",
+    "./server-vars-to-path-params.js": "./server-vars-to-path-params.js",
+    "./server-vars-to-x-ms-parameterized-host.js": "./server-vars-to-x-ms-parameterized-host.js",
+    "./type-null-to-enum.js": "./type-null-to-enum.js",
+    "./type-null-to-nullable.js": "./type-null-to-nullable.js",
+    "./urlencoded-to-string.js": "./urlencoded-to-string.js",
+    "./x-enum-to-ms.js": "./x-enum-to-ms.js"
+  },
+  "//": "All scripts should run in POSIX sh and Windows cmd.exe",
+  "scripts": {
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -u",
+    "clean": "rimraf coverage && rimraf doc",
+    "doc": "npm run doc-js && npm run doc-spec",
+    "doc-js": "rimraf doc/api && jsdoc -c jsdoc.conf.json .",
+    "doc-spec": "rimraf doc/spec && mkdir doc/spec && mocha --reporter doc --recursive test | nodecat doc-src/spec/header.xhtml - doc-src/spec/footer.xhtml > doc/spec/index.xhtml",
+    "lint": "npm run lint-js && npm run lint-doc",
+    "lint-doc": "jsdoc -t templates/silent -c jsdoc-lint.conf.json . && echo JSDoc passed.",
+    "lint-js": "eslint --report-unused-disable-directives . && echo ESLint passed.",
+    "release": "git -C doc push && git push --follow-tags origin main gh-pages && echo \"Create a GitHub Release (from CHANGELOG.md) to run publish workflow.\"",
+    "postversion": "rimraf doc && git clone -b gh-pages -l -q . doc && npm run doc && git -C doc add . && git -C doc commit -n -m \"Docs for v$npm_package_version\"",
+    "preversion": "node ./scripts/preversion.js && npm run test-cov && c8 check-coverage --statements 85 --lines 85 && depcheck --ignore-dirs doc --ignores=\"eslint-*,rimraf\" && david && git-branch-is main && hub-ci-status -vv --wait",
+    "test": "npm run lint && npm run test-unit",
+    "test-cov": "npm run lint && npm run test-unit-cov",
+    "test-unit": "node --disable-proto=throw --throw-deprecation --unhandled-rejections=strict node_modules/mocha/bin/mocha.js --parallel --recursive test",
+    "test-unit-cov": "c8 --reporter=lcov --reporter=text npm run test-unit",
+    "version": "npm run changelog && echo && echo === Please edit CHANGELOG.md as desired, then exit === && echo && \"${npm_config_shell:-${SHELL:-bash}}\" && git commit -m \"Update CHANGELOG.md for $npm_package_version\" CHANGELOG.md",
+    "version-deps": "npm install conventional-changelog-cli david depcheck git-branch-is hub-ci-status"
+  },
+  "dependencies": {
+    "@kevinoid/dotnet-identifier-case": "^1.0.0",
+    "fast-json-stable-stringify": "^2.1.0",
+    "json-ptr": "^3.0.1",
+    "json-schema-intersect": "^0.1.0",
+    "openapi-transformer-base": "^1.1.0"
+  },
+  "devDependencies": {
+    "@kevinoid/eslint-config": "^34.0.0",
+    "c8": "^11.0.0",
+    "deep-freeze": "^0.0.1",
+    "eslint": "^9.35.0",
+    "globals": "^17.0.0",
+    "jsdoc": "^4.0.0",
+    "mocha": "^11.0.1",
+    "nodecat": "^3.0.0",
+    "rimraf": "^6.1.2"
+  },
+  "engines": {
+    "node": "20 || >=22",
+    "npm": ">=1.3.7"
+  },
+  "mocha": {
+    "checkLeaks": true,
+    "exit": false
+  },
+  "c8": {
+    "exclude": [
+      "test",
+      "test-lib"
+    ]
+  },
+  "david": {
+    "// eslint": "Must match version from peerDependencies of @kevinoid/eslint-plugin",
+    "ignore": [
+      "eslint"
+    ]
+  }
+}

package/path-parameters-to-operations.js

@@ -0,0 +1,63 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/path-parameters-to-operations.js"
+ */
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const PATH_METHODS = [
+  'delete',
+  'get',
+  'head',
+  'options',
+  'patch',
+  'post',
+  'put',
+  'trace',
+];
+
+/**
+ * Transformer to move parameters defined on Path Item Objects to the beginning
+ * of the parameters array of the Operation Objects so that they will be
+ * generated in the desired order (path-first).
+ */
+export default class PathParametersToOperationTransformer
+  extends OpenApiTransformerBase {
+  // eslint-disable-next-line class-methods-use-this
+  transformPathItem(pathItem) {
+    if (!Array.isArray(pathItem.parameters)
+      || pathItem.parameters.length === 0) {
+      return pathItem;
+    }
+
+    const {
+      parameters,
+      ...newPathItem
+    } = pathItem;
+    for (const method of PATH_METHODS) {
+      if (Object.hasOwn(pathItem, method)) {
+        const operation = pathItem[method];
+        const opParams = operation.parameters;
+        newPathItem[method] = {
+          ...operation,
+          // TODO: Operation parameters can override path parameters (where
+          // .name and .in match).  Either can be $ref.  Handle these.
+          parameters:
+            !Array.isArray(opParams) || opParams.length === 0 ? parameters
+              : [...parameters, ...opParams],
+        };
+      }
+    }
+
+    return newPathItem;
+  }
+
+  // Performance optimization:  Only need to transform paths.
+  transformOpenApi(spec) {
+    return {
+      ...spec,
+      paths: this.transformPaths(spec.paths),
+    };
+  }
+}

package/pattern-properties-to-additional-properties.js

@@ -0,0 +1,62 @@
+/**
+ * @copyright Copyright 2021 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/pattern-properties-to-additional-properties.js"
+ */
+
+import { isDeepStrictEqual } from 'node:util';
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+/**
+ * Transformer to combine any patternProperties into additionalProperties (for
+ * conversion from OpenAPI 3.1 to prior versions before patternProperties
+ * was supported).
+ * https://github.com/OAI/OpenAPI-Specification/issues/687
+ */
+export default class PatternPropertiesToAdditionalPropertiesTransformer
+  extends OpenApiTransformerBase {
+  transformSchema(schema) {
+    if (typeof schema !== 'object' || schema === null) {
+      return schema;
+    }
+
+    schema = super.transformSchema(schema);
+
+    const {
+      patternProperties,
+      ...newSchema
+    } = schema;
+    if (typeof patternProperties !== 'object' || patternProperties === null) {
+      return schema;
+    }
+
+    const uniquePropSchemas = [];
+    for (const propSchema of Object.values(patternProperties)) {
+      if (propSchema !== undefined
+        && !uniquePropSchemas.some((s) => isDeepStrictEqual(s, propSchema))) {
+        uniquePropSchemas.push(propSchema);
+      }
+    }
+
+    if (uniquePropSchemas.length === 0) {
+      // Remove empty patternProperties object.
+      return newSchema;
+    }
+
+    const { additionalProperties } = schema;
+    if (additionalProperties !== undefined
+      && !uniquePropSchemas
+        .some((s) => isDeepStrictEqual(s, additionalProperties))) {
+      uniquePropSchemas.push(additionalProperties);
+    }
+
+    if (uniquePropSchemas.length === 1) {
+      newSchema.additionalProperties = uniquePropSchemas[0];
+    } else {
+      newSchema.additionalProperties = { anyOf: uniquePropSchemas };
+    }
+
+    return newSchema;
+  }
+}

package/queries-to-x-ms-paths.js

@@ -0,0 +1,63 @@
+/**
+ * @copyright Copyright 2019 Kevin Locke <kevin@kevinlocke.name>
+ * @license MIT
+ * @module "openapi-transformers/queries-to-x-ms-paths.js"
+ */
+
+import assert from 'node:assert';
+import { debuglog } from 'node:util';
+
+import OpenApiTransformerBase from 'openapi-transformer-base';
+
+const debug = debuglog('openapi-transformers:queries-to-x-ms-paths');
+
+/**
+ * Transformer to move paths with query parameters from paths to x-ms-paths for
+ * Autorest.
+ *
+ * https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-paths
+ *
+ * This is used to work around lack of support for multiple operations with the
+ * same path and method:
+ * https://github.com/OAI/OpenAPI-Specification/issues/791
+ *
+ * Putting query in path is not allowed by any current version of OpenAPI
+ * https://github.com/OAI/OpenAPI-Specification/issues/468#issuecomment-142393969
+ * but it has the benefit of working with lots of tooling without support for
+ * x-ms-paths (e.g. for linting, docs generation, etc.)
+ */
+export default class QueriesToXMsPathsTransformer
+  extends OpenApiTransformerBase {
+  // Override as performance optimization, since only transforming paths
+  // eslint-disable-next-line class-methods-use-this
+  transformOpenApi(spec) {
+    if (!spec || !spec.paths) {
+      return spec;
+    }
+
+    const queryPaths = Object.keys(spec.paths)
+      .filter((path) => path.includes('?'));
+
+    if (queryPaths.length === 0) {
+      return spec;
+    }
+
+    const paths = { ...spec.paths };
+    const xMsPaths = { ...spec['x-ms-paths'] };
+    for (const path of queryPaths) {
+      debug('moving %s from paths to x-ms-paths', path);
+      assert.ok(
+        !Object.hasOwn(xMsPaths, path),
+        `${path} already present in x-ms-paths`,
+      );
+      xMsPaths[path] = paths[path];
+      delete paths[path];
+    }
+
+    return {
+      ...spec,
+      paths,
+      'x-ms-paths': xMsPaths,
+    };
+  }
+}