OpenAPI Transformers

A collection of classes for transforming OpenAPI documents, particularly for compatibility with code generators like Autorest and OpenAPI Generator.

Introductory Example

To rename all Schema Objects defined in components of an OpenAPI document:

import RenameComponentsTransformer from '@kevinoid/openapi-transformers';
import openapi from './openapi.json' with { type: 'json' };

function renameSchema(schemaName) {
    return `New${schemaName}`;
}

const transformer = new RenameComponentsTransformer({ schemas: renameSchema });
console.log(transformer.transformOpenApi(openapi));

Example with @kevinoid/openapi-transformer-cli

To remove headers from responses in an OpenAPI document:

openapi-transformer -t @kevinoid/openapi-transformers/remove-response-headers.js <openapi-old.json >openapi-new.json

Transformers

Transformer	Description
AddTagToOperationIdsTransformer	Prefix operationId with the first tag name and an underscore.
AddXMsEnumNameTransformer	Add x-ms-enum.name from schema name, if not present.
AddXMsEnumValueNamesTransformer	Add x-ms-enum.values.name to enums where the name generated by Autorest differs from the Microsoft C# Capitalization Rules for Identifiers.
AdditionalPropertiesToObjectTransformer	Replace boolean additionalProperties with a Schema.
AdditionalPropertiesToUnconstrainedTransformer	Replace additionalProperties (and patternProperties) with an unconstrained schema alongside other properties.
AnyOfNullToNullableTransformer	Replace type: 'null' in anyOf with nullable: true (for OAS 3.0).
BinaryStringToFileTransformer	Replace type: string with format: binary (or format: file) with type: file.
BoolEnumToBoolTransformer	Replace enum: [true, false] with type: boolean.
ClearHtmlResponseSchemaTransformer	Remove response content for the text/html media type.
ClientParamsToGlobalTransformer	Move parameters with x-ms-parameter-location: client defined on Path Item Objects and Operation Objects to the Components or Definitions Object.
ConstToEnumTransformer	Convert Schema Objects with const to enum.
AssertPropertiesTransformer	Throw an Error when given properties are present.
EscapeEnumValuesTransformer	Escape string enum values appropriately for C# string literals.
ExclusiveMinMaxToBoolTransformer	Convert Schema Objects with numeric values for exclusiveMaximum and/or exclusiveMinimum to boolean values with corresponding maximum and/or minimum.
FormatToTypeTransformer	Convert known formats in an OAS3 doc to types.
InlineNonObjectSchemaTransformer	Inline schemas with non-object type.
MergeAllOfTransformer	Merge allOf schemas into the parent schema.
MergeAnyOfTransformer	Merge anyOf schemas into the parent schema.
MergeOneOfTransformer	Merge oneOf schemas into the parent schema.
NullableNotRequiredTransformer	Make properties which are nullable non-required.
NullableToTypeNullTransformer	Add 'null' to type of Schema Objects with nullable: true or x-nullable: true.
OpenApi31To30Transformer	Convert an OpenAPI 3.1.* document to OpenAPI 3.0.3.
PathParametersToOperationTransformer	Move parameters defined on Path Item Objects to the beginning of the parameters array of the Operation Objects.
PatternPropertiesToAdditionalPropertiesTransformer	Combine any patternProperties into additionalProperties.
QueriesToXMsPathsTransformer	Move paths with query parameters from paths to x-ms-paths.
ReadOnlyNotRequiredTransformer	Ensure readOnly schema properties are not required.
RefPathParametersTransformer	Move Parameters defined on Path Item Objects to global parameters which are referenced in the Path Item.
RemoveDefaultOnlyResponseProducesTransformer	Remove produces from Operations with only a default response.
RemovePathsWithServersTransformer	Remove Path Item Objects which have servers.
RemoveQueryFromPathsTransformer	Remove query component of path in Paths Object.
RemoveRefSiblingsTransformer	Remove properties from Reference Objects.
RemoveRequestBodyTransformer	Remove requestBody from operations on a given set of HTTP methods.
RemoveResponseHeadersTransformer	Remove headers from Response objects.
RemoveSecuritySchemeIfTransformer	Remove security schemes matching a given predicate.
RemoveTypeIfTransformer	Remove type from Schema Objects where type matches a given predicate.
RenameComponentsTransformer	Rename components.
ReplacedByToDescriptionTransformer	Convert x-deprecated.replaced-by to x-deprecated.description, if not present.
ServerVarsToPathParamsTransformer	Convert Server Variables in path portion to Parameters on Path Item Objects.
ServerVarsToParamHostTransformer	Convert Server Variables in host portion to x-ms-parameterized-host.
TypeNullToEnumTransformer	Convert Schema Objects with type: 'null' to enum: [null].
TypeNullToNullableTransformer	Convert Schema Objects with 'null' in type to nullable: true.
UrlencodedToStringTransformer	Change request parameter types to string for operations which only consume application/x-www-form-urlencoded.
XEnumToXMsEnumTransformer	Convert x-enum-descriptions and x-enum-varnames to x-ms-enum.

Installation

This package can be installed using npm, either globally or locally, by running:

npm install @kevinoid/openapi-transformers

Recipes

More examples can be found in the test specifications.

API Docs

To use this module as a library, see the API Documentation.

Contributing

Contributions are appreciated. Contributors agree to abide by the Contributor Covenant Code of Conduct. If this is your first time contributing to a Free and Open Source Software project, consider reading How to Contribute to Open Source in the Open Source Guides.

If the desired change is large, complex, backwards-incompatible, can have significantly differing implementations, or may not be in scope for this project, opening an issue before writing the code can avoid frustration and save a lot of time and effort.

License

This project is available under the terms of the MIT License. See the summary at TLDRLegal.