Skip to content

Commit 00844fe

Browse files
committed
docs: Fill out README.md
With some basic information about the package and the available Transformer classes. Signed-off-by: Kevin Locke <[email protected]>
1 parent 94cd004 commit 00844fe

File tree

1 file changed

+75
-13
lines changed

1 file changed

+75
-13
lines changed

README.md

+75-13
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,88 @@
1-
Project Template
2-
================
1+
OpenAPI Transformers
2+
====================
33

44
[![Build Status](https://img.shields.io/github/actions/workflow/status/kevinoid/openapi-transformers/node.js.yml?branch=main&style=flat&label=build)](https://github.com/kevinoid/openapi-transformers/actions?query=branch%3Amain)
55
[![Coverage](https://img.shields.io/codecov/c/github/kevinoid/openapi-transformers/main.svg?style=flat)](https://app.codecov.io/gh/kevinoid/openapi-transformers/branch/main)
66
[![Dependency Status](https://img.shields.io/librariesio/release/npm/@kevinoid/openapi-transformers.svg?style=flat)](https://libraries.io/npm/@kevinoid%2Fopenapi-transformers)
77
[![Supported Node Version](https://img.shields.io/node/v/@kevinoid/openapi-transformers.svg?style=flat)](https://www.npmjs.com/package/@kevinoid/openapi-transformers)
88
[![Version on NPM](https://img.shields.io/npm/v/@kevinoid/openapi-transformers.svg?style=flat)](https://www.npmjs.com/package/@kevinoid/openapi-transformers)
99

10-
A Node.js/npm project template with [codecov](https://codecov.io/),
11-
[coveralls](https://coveralls.io/), [ESLint](https://eslint.org/),
12-
[conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli),
13-
[c8](https://github.com/bcoe/c8), [JSDoc](http://usejsdoc.org/), and
14-
[mocha](https://mochajs.org/).
10+
A collection of classes for transforming
11+
[OpenAPI](https://github.com/OAI/OpenAPI-Specification/) documents,
12+
particularly for compatibility with code generators like
13+
[Autorest](https://github.com/Azure/autorest) and [OpenAPI
14+
Generator](https://openapi-generator.tech/).
1515

16-
It is the template that I am using for my own Node.js projects, which
17-
represents my current preferences. I am not advocating for these choices nor
18-
this template specifically, although I am happy to discuss or explain any
19-
choices made herein. It is being published both for my own convenience and
20-
in case it may be useful to others with similar tastes.
2116

2217
## Introductory Example
2318

19+
To rename all Schema Objects defined in `components` of an OpenAPI document:
20+
2421
```js
22+
import RenameComponentsTransformer from '@kevinoid/openapi-transformers';
23+
import openapi from './openapi.json' with { type: 'json' };
24+
25+
function renameSchema(schemaName) {
26+
return `New${schemaName}`;
27+
}
28+
29+
const transformer = new RenameComponentsTransformer({ schemas: renameSchema });
30+
console.log(transformer.transformOpenApi(openapi));
31+
```
32+
33+
34+
## Example with [`@kevinoid/openapi-transformer-cli`](https://github.com/kevinoid/openapi-transformer-cli)
35+
36+
To remove `headers` from responses in an OpenAPI document:
37+
38+
```sh
39+
openapi-transformer -t @kevinoid/openapi-transformers/remove-response-headers.js <openapi-old.json >openapi-new.json
2540
```
2641

27-
## Features
42+
43+
## Transformers
44+
45+
| **Transformer** | **Description** |
46+
| ---------------------------------------------------------------------------------------------------- | --------------- |
47+
| [AddTagToOperationIdsTransformer](add-tag-to-operation-ids.js) | Prefix `operationId` with the first tag name and an underscore. |
48+
| [AddXMsEnumNameTransformer](add-x-ms-enum-name.js) | Add `x-ms-enum.name` from schema name, if not present. |
49+
| [AddXMsEnumValueNamesTransformer](add-x-ms-enum-value-names.js) | Add `x-ms-enum.values.name` to enums where the name generated by Autorest differs from the Microsoft C# Capitalization Rules for Identifiers. |
50+
| [AdditionalPropertiesToObjectTransformer](additional-properties-to-object.js) | Replace boolean `additionalProperties` with a Schema. |
51+
| [AdditionalPropertiesToUnconstrainedTransformer](additional-properties-to-unconstrained.js) | Replace `additionalProperties` (and `patternProperties`) with an unconstrained schema alongside other properties. |
52+
| [BinaryStringToFileTransformer](binary-string-to-file.js) | Replace `type: string` with `format: binary` (or `format: file`) with `type: file`. |
53+
| [BoolEnumToBoolTransformer](bool-enum-to-bool.js) | Replace `enum: [true, false]` with `type: boolean`. |
54+
| [ClearHtmlResponseSchemaTransformer](clear-html-response-schema.js) | Remove response content for the `text/html` media type. |
55+
| [ClientParamsToGlobalTransformer](client-params-to-global.js) | Move parameters with `x-ms-parameter-location: client` defined on Path Item Objects and Operation Objects to the Components or Definitions Object. |
56+
| [ConstToEnumTransformer](const-to-enum.js) | Convert Schema Objects with `const` to `enum`. |
57+
| [EscapeEnumValuesTransformer](escape-enum-values.js) | Escape string enum values appropriately for C# string literals. |
58+
| [ExclusiveMinMaxToBoolTransformer](exclusive-min-max-to-bool.js) | Convert Schema Objects with numeric values for `exclusiveMaximum` and/or `exclusiveMinimum` to boolean values with corresponding `maximum` and/or `minimum`. |
59+
| [FormatToTypeTransformer](format-to-type.js) | Convert known formats in an OAS3 doc to types. |
60+
| [InlineNonObjectSchemaTransformer](inline-non-object-schemas.js) | Inline schemas with non-object type. |
61+
| [MergeSubschemasTransformer](merge-subschemas.js) | Merge `allOf`/`anyOf`/`oneOf` schemas into the parent schema. |
62+
| [NullableNotRequiredTransformer](nullable-not-required.js) | Make properties which are `nullable` non-`required`. |
63+
| [NullableToTypeNullTransformer](nullable-to-type-null.js) | Add `'null'` to `type` of Schema Objects with `nullable: true` or `x-nullable: true`. |
64+
| [OpenApi31To30Transformer](openapi31to30.js) | Convert an OpenAPI 3.1.* document to OpenAPI 3.0.3. |
65+
| [PathParametersToOperationTransformer](path-parameters-to-operations.js) | Move parameters defined on Path Item Objects to the beginning of the parameters array of the Operation Objects. |
66+
| [PatternPropertiesToAdditionalPropertiesTransformer](pattern-properties-to-additional-properties.js) | Combine any `patternProperties` into `additionalProperties`. |
67+
| [QueriesToXMsPathsTransformer](queries-to-x-ms-paths.js) | Move paths with query parameters from `paths` to `x-ms-paths`. |
68+
| [ReadOnlyNotRequiredTransformer](read-only-not-required.js) | Ensure `readOnly` schema properties are not `required`. |
69+
| [RefPathParametersTransformer](ref-path-parameters.js) | Move Parameters defined on Path Item Objects to global parameters which are referenced in the Path Item. |
70+
| [RemoveDefaultOnlyResponseProducesTransformer](remove-default-only-response-produces.js) | Remove `produces` from Operations with only a default response. |
71+
| [RemovePathsWithServersTransformer](remove-paths-with-servers.js) | Remove Path Item Objects which have `servers`. |
72+
| [RemoveQueryFromPathsTransformer](remove-query-from-paths.js) | Remove query component of path in Paths Object. |
73+
| [RemoveRefSiblingsTransformer](remove-ref-siblings.js) | Remove properties from Reference Objects. |
74+
| [RemoveRequestBodyTransformer](remove-request-body.js) | Remove `requestBody` from operations on a given set of HTTP methods. |
75+
| [RemoveResponseHeadersTransformer](remove-response-headers.js) | Remove `headers` from Response objects.
76+
| [RemoveSecuritySchemeIfTransformer](remove-security-scheme-if.js) | Remove `security` schemes matching a given predicate. |
77+
| [RemoveTypeIfTransformer](remove-type-if.js) | Remove `type` from Schema Objects where `type` matches a given predicate. |
78+
| [RenameComponentsTransformer](rename-components.js) | Rename `components`. |
79+
| [ReplacedByToDescriptionTransformer](replaced-by-to-description.js) | Convert `x-deprecated.replaced-by` to `x-deprecated.description`, if not present. |
80+
| [ServerVarsToPathParamsTransformer](server-vars-to-path-params.js) | Convert Server Variables in path portion to Parameters on Path Item Objects. |
81+
| [ServerVarsToParamHostTransformer](server-vars-to-x-ms-parameterized-host.js) | Convert Server Variables in host portion to `x-ms-parameterized-host`. |
82+
| [TypeNullToEnumTransformer](type-null-to-enum.js) | Convert Schema Objects with `type: 'null'` to `enum: [null]`. |
83+
| [TypeNullToNullableTransformer](type-null-to-nullable.js) | Convert Schema Objects with `'null'` in `type` to `nullable: true`. |
84+
| [UrlencodedToStringTransformer](urlencoded-to-string.js) | Change request parameter types to string for operations which only consume `application/x-www-form-urlencoded`. |
85+
| [XEnumToXMsEnumTransformer](x-enum-to-ms.js) | Convert `x-enum-descriptions` and `x-enum-varnames` to `x-ms-enum`. |
2886

2987

3088
## Installation
@@ -37,16 +95,19 @@ running:
3795
npm install @kevinoid/openapi-transformers
3896
```
3997

98+
4099
## Recipes
41100

42101
More examples can be found in the [test
43102
specifications](https://kevinoid.github.io/openapi-transformers/spec).
44103

104+
45105
## API Docs
46106

47107
To use this module as a library, see the [API
48108
Documentation](https://kevinoid.github.io/openapi-transformers/api).
49109

110+
50111
## Contributing
51112

52113
Contributions are appreciated. Contributors agree to abide by the [Contributor
@@ -62,6 +123,7 @@ significantly differing implementations, or may not be in scope for this
62123
project, opening an issue before writing the code can avoid frustration and
63124
save a lot of time and effort.
64125

126+
65127
## License
66128

67129
This project is available under the terms of the [MIT License](LICENSE.txt).

0 commit comments

Comments
 (0)