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.