🇺🇸 English | 🇷🇺 Русский | 🇨🇳 中文

OpenAPI Modifier

A tool for modifying OpenAPI specifications using customizable rules.

This package allows you to automate the process of modifying OpenAPI specifications by applying a set of predefined rules.

Main features

- Modification of OpenAPI specifications in YAML and JSON formats
- Flexible rule system for specification changes
- Support for both CLI and programmatic usage with TypeScript support

> [!IMPORTANT]
> Supports OpenAPI 3.1, 3.0. We haven't tested OpenAPI 2 support as the format is deprecated and we recommend migrating your documentation to OpenAPI 3.0.

Motivation and use cases

OpenAPI describing backend API is not always perfect: it may contain errors, inaccuracies, or certain features that break other tools, such as code generation or type generation.

Storing information about changes in a declarative format to maintain context and relevance of each change is especially useful in large teams.

Installation

`bash
npm install --save-dev openapi-modifier
`

Usage

$3

`shell
npx openapi-modifier --input=input/openapi.yml --output=output/openapi.yml --config=openapi-modifier.config.js
`

Example of using as CLI via NPX

CLI parameters:

| Option | Description | Example | Default |
| -------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- |----------------------------------------------|
| input | [required] input file, openapi specification/documentation | input/openapi.yml | |
| output | [required] output file, openapi specification/documentation | output/openapi.yml | |
| config | path to the configuration file. For detailed configuration description see below | openapi-modifier.config.js | openapi-modifier.config.(js\ts\json\yaml\yml) |

For more details about the configuration file, see below

If the configuration path is not specified, the default configuration is taken from the openapi-modifier.config.js file relative to the launch directory.

You can use configs with the following extensions: .ts, .js, .yaml, .yml, .json.

$3

`shell
npm i --save-dev openapi-modifier

openapi-modifier --input=input/openapi.yml --output=output/openapi.yml --config=openapi-modifier.config.js
`

Example of using as CLI

CLI parameters:

| Option | Description | Example | Default |
| -------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- |----------------------------------------------|
| input | [required] input file, openapi specification/documentation | input/openapi.yml | |
| output | [required] output file, openapi specification/documentation | output/openapi.yml | |
| config | path to the configuration file. For detailed configuration description see below | openapi-modifier.config.js | openapi-modifier.config.(js\ts\json\yaml\yml) |

For more details about the configuration file, see below

If the configuration path is not specified, the default configuration is taken from the openapi-modifier.config.js file relative to the launch directory.

You can use configs with the following extensions: .ts, .js, .yaml, .yml, .json.

$3

`typescript
import { openapiModifier } from 'openapi-modifier';

(async () => {
try {
await openapiModifier({
input: 'input/openapi.yml',
output: 'output/openapi.yml',
pipeline: [
{
rule: 'remove-operation-id',
config: {
ignore: [],
},
},
],
});

process.exit(0);
} catch (error) {
console.error(error);
process.exit(1);
}
})();
`

Example of programmatic usage

Configuration

Create a configuration file (e.g., openapi-modifier.config.js or openapi-modifier.config.ts) with the following structure:

`javascript
module.exports = {
// (optional) Logger settings
logger: {
verbose: true, // Enable detailed logging
minLevel: 0 // Minimum logging level: 0 - trace, 1 - debug, 2 - info, 3 - warn, 4 - error
},
// Path to input OpenAPI specification file
input: './openapi.yaml',
// Path to output file
output: './modified-openapi.yaml',
// Pipeline of rules to apply (see below for all available rules with configuration examples)
pipeline: [
{
rule: "change-content-type",
disabled: false, // (optional) Disable rule
config: {
map: {
"/": "application/json"
}
}
}
// Other rules...
]
}
`

> [!IMPORTANT]
> Thanks to the pipeline structure of rules, you can:
> - edit the result of the previous stage with the next stage, thus building a sequence of necessary changes;
> - use rules as many times as needed and in the required sequence;

Available Rules

| Rule | Short Description |
|------------------------------------------------------------------| ---- |
| change-content-type | Changes content types in the OpenAPI specification according to the replacement dictionary |
| change-endpoints-basepath | Changes basepaths of endpoints according to the replacement dictionary |
| filter-by-content-type | The rule allows filtering content types in the OpenAPI specification. It enables explicit specification of which content types should be kept or removed from the specification. The rule applies to all API components, including requests, responses, and common components. |
| filter-endpoints | The rule allows filtering endpoints in the OpenAPI specification based on their paths and methods. It enables explicit specification of which endpoints should be kept or removed from the specification. The rule supports both exact matching and regular expression-based filtering. |
| merge-openapi-spec | Merges two OpenAPI specifications into one. Allows merging the current specification with an additional specification from a specified file. Supports working with files in JSON and YAML formats. |
| patch-component-schema | This rule allows modifying the component schema in the OpenAPI specification. |
| patch-endpoint-parameter-schema | The rule allows modifying the schema of endpoint parameters in the OpenAPI specification. |
| patch-endpoint-request-body-schema | Rule for modifying the request body schema in OpenAPI specification. Allows to modify the request schema for a specified endpoint. |
| patch-endpoint-response-schema | The rule allows modifying the response schema for endpoints in the OpenAPI specification. |
| patch-endpoint-schema | The rule allows modifying the entire endpoint schema in the OpenAPI specification. Unlike other patching rules that work with individual parts of the endpoint (parameters, request body, responses), this rule can modify the entire endpoint structure, including all its components. |
| remove-deprecated | The rule allows removing deprecated elements from the OpenAPI specification. It can remove deprecated components, endpoints, parameters, and properties, while providing the ability to ignore specific elements and display descriptions of removed elements. |
| remove-max-items | Removes the maxItems property from all schemas in the OpenAPI specification. |
| remove-min-items | Removes the minItems property from all schemas in the OpenAPI specification. |
| remove-operation-id | Removes operationId from all operations in the OpenAPI specification, except those specified in the ignore list |
| remove-parameter | Removes a parameter from an endpoint in the OpenAPI specification |
| remove-unused-components | Removes unused components from the OpenAPI specification. The rule analyzes all component references in the document and removes those that are not used anywhere. |

Short descriptions of the rules

$3

Changes content types in the OpenAPI specification according to the replacement dictionary

#### Config

| Parameter | Description | Example | Typing | Default |
|----------|-----------------------------------|----------------------------|------------------------|-----------|
| map | [required] Dictionary for content type replacements | {"/": "application/json"} | Record | {} |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "change-content-type",
config: {
map: {
"/": "application/json" // replace all content types with application/json
}
},
}
// ... other rules
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "change-content-type",
config: {
map: {
"application/xml": "application/json", // replace application/xml with application/json
"text/plain": "application/json", // replace text/plain with application/json
"/": "application/json" // replace all other content types with application/json
}
},
}
// ... other rules
]
}
`

More details about rule change-content-type

----------------------

$3

Changes basepaths of endpoints according to the replacement dictionary

#### Config

| Parameter | Description | Example | Typing | Default |
|-----------------------------|-----------------------------------------------------------------------|----------------------|--------------------------|-----------|
| map | [required] Map of path prefixes to replace | {"/api/v1": "/v1"} | Record | {} |
| ignoreOperationCollisions | [optional] Whether to ignore operation collisions during path replacement | true | boolean | false |


Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "change-endpoints-basepath",
config: {
map: {
'/public/api': '', // remove the /public/api prefix from all paths
},
},
}
// ... other rules
]
}
`

Example of a more detailed configuration:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "change-endpoints-basepath",
config: {
map: {
'/public/v1/service/api': '/api', // replace the prefix /public/v1/service/api with /api
},
ignoreOperationCollisions: false, // do not ignore operation conflicts when replacing paths
},
}
// ... other rules
]
}
`

More details about rule change-endpoints-basepath

----------------------

$3

The rule allows filtering content types in the OpenAPI specification. It enables explicit specification of which content types should be kept or removed from the specification. The rule applies to all API components, including requests, responses, and common components.

#### Config

| Parameter | Description | Example | Type | Default |
|------------|------------------------------------------------------|------------------------|----------------|---------|
| enabled | [optional] List of allowed content types. If not specified, all types not listed in disabled are kept | ['application/json'] | Array | |
| disabled | [optional] List of forbidden content types | ['multipart/form-data'] | Array | |

Configuration examples:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-by-content-type",
config: {
enabled: ['application/json'], // keep only application/json content type, remove all others
}
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-by-content-type",
config: {
disabled: ['multipart/form-data'], // remove multipart/form-data content type, keep all others
}
}
// ... other rules
]
}
`

> [!IMPORTANT]
> 1. If both enabled and disabled parameters are specified, the enabled filter is applied first, followed by disabled
> 2. The rule outputs warnings for content types specified in the configuration but not found in the specification

More details about rule filter-by-content-type

----------------------

$3

The rule allows filtering endpoints in the OpenAPI specification based on their paths and methods. It enables explicit specification of which endpoints should be kept or removed from the specification. The rule supports both exact matching and regular expression-based filtering.

#### Config

> [!IMPORTANT]
> The rule works either in enabled mode - filtering endpoints from the specification (when either enabled or enabledPathRegExp is specified in the configuration), or in disabled mode - excluding endpoints from the specification (when either disabled or disabledPathRegExp is specified in the configuration)

| Parameter | Description | Example | Typing | Default |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------------|-----------------|
| enabled | List of endpoints to keep | [{"method": "GET", "path": "/pets"}] | Array | - |
| enabledPathRegExp | List of regular expressions for paths to keep | [/^\/api\/v1/] | Array | - |
| disabled | List of endpoints to exclude | [{"method": "POST", "path": "/pets"}] | Array | - |
| disabledPathRegExp | List of regular expressions for paths to exclude | [/^\/internal/] | Array | - |
| printIgnoredEndpoints | Whether to output information about excluded endpoints to the log | true | boolean | false |

Configuration examples:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-endpoints",
config: {
enabled: [
'GET /foo/ping' // keep only GET /foo/ping endpoint, all others will be removed
],
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-endpoints",
config: {
enabledPathRegExp: [
/\/public/ // keep all endpoints whose path contains /public
],
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-endpoints",
config: {
disabled: [
'GET /foo/ping' // remove GET /foo/ping endpoint, all others will remain
],
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "filter-endpoints",
config: {
disabledPathRegExp: [
/\/internal/ // remove all endpoints whose path contains /internal
],
printIgnoredEndpoints: true, // print information about removed endpoints to console
},
}
// ... other rules
]
}
`

More details about rule filter-endpoints

----------------------

$3

Merges two OpenAPI specifications into one. Allows merging the current specification with an additional specification from a specified file. Supports working with files in JSON and YAML formats.

#### Config

| Parameter | Description | Example | Type | Default |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|----------|-----------|
| path | [required] Path to the OpenAPI configuration that needs to be merged into the current specification. The path can be relative (relative to package.json location) or absolute (e.g., obtained via __dirname relative to config location). Supported formats: .json, .yml, *.yaml. | temp-openapi-specs/new-list-endpoints.yaml | string | |
| ignoreOperationCollisions| When merging multiple specifications, conflicts may occur when there are identical endpoints. By default, the tool prohibits merging if collisions are found to prevent unexpected changes in the source specification. This setting allows you to ignore conflicts and merge specifications anyway. | true | boolean | false |
| ignoreComponentCollisions| When merging multiple specifications, conflicts may occur when there are identical common components. By default, the tool prohibits merging if collisions are found to prevent unexpected changes in the source specification. This setting allows you to ignore conflicts and merge specifications anyway. | true | boolean | false |

> [!IMPORTANT]
> If you need to merge multiple specifications, you can use this rule multiple times in the general pipeline configuration.

Configuration examples:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "merge-openapi-spec",
config: {
path: 'temp-openapi-specs/new-list-endpoints.yaml', // specify path to specification file to merge
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "merge-openapi-spec",
config: {
path: __dirname + '../temp-openapi-specs/new-list-endpoints.json', // specify absolute path to specification file
ignoreOperationCollisions: true, // ignore operation conflicts during merge
ignoreComponentCollisions: true, // ignore component conflicts during merge
},
}
// ... other rules
]
}
`

More details about rule merge-openapi-spec

----------------------

$3

This rule allows modifying the component schema in the OpenAPI specification.

#### Config

| Parameter | Description | Example | Typing | Default |
| -------- |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|-------------------------------------------|-----------------------------------------|
| descriptor | [required] Description of the component to modify. Learn more about the differences between simple and object component descriptors with correction | "Pet.name" or {"componentName": "Pet", "correction": "properties.name"} | string \ { componentName: string; correction: string } | - |
| patchMethod | Patch application method. Learn more about the differences between merge and deepmerge methods | "merge" | "merge" \ "deepmerge" | "merge" |
| schemaDiff | [required] Schema for patching. Detailed examples of OpenAPI specifications | {"type": "string", "description": "New description"} | OpenAPISchema | - |

> [!IMPORTANT]
> Nuances of setting the descriptor parameter:
> - Following $refs is not supported. Because it may cause unintended changes in shared components, and thus create unexpected changes elsewhere in the specification. In this case, it's better to modify the entity referenced by $ref directly;
> - If you need to traverse array elements - you need to specify [] in the descriptor, for example, TestSchemaDTO[].test
> - If you need to traverse oneOf, allOf, anyOf, you need to specify oneOf[{number}], allOf[{number}] or anyOf[{number}] in the descriptor, for example, TestObjectDTO.oneOf[1].TestSchemaDTO, TestObjectDTO.allOf[1].TestSchemaDTO or TestObjectDTO.anyOf[1].TestSchemaDTO;

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-component-schema",
config: {
descriptor: 'TestDTO', // specify the component to modify
schemaDiff: {
type: 'string', // change component type to string
},
},
}
// ... other rules
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-component-schema",
config: {
descriptor: 'TestObjectDTO.oneOf[0].TestArraySchemaDTO[]', // specify path to component in complex structure
schemaDiff: {
type: 'string', // change component type to string
enum: ['foo', 'bar'], // add enum to component
},
patchMethod: 'deepmerge', // use deepmerge method for deep merging changes
},
}
// ... other rules
]
}
`

More details about rule patch-component-schema

----------------------

$3

The rule allows modifying the schema of endpoint parameters in the OpenAPI specification.

#### Config

| Parameter | Description | Example | Typing | Default |
|-----------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|--------------|
| endpointDescriptor | [required] Specifies which endpoint's request parameter schema needs to be changed. | 'GET /api/list' | string \ { path: string; method: string } | |
| parameterDescriptor | [required] Specifies which request parameter, referenced by endpointDescriptor, needs to be changed. | 'TestSchemaDTO', 'TestSchemaDTO.test', 'TestSchemaDTO[].testField', 'TestObjectDTO.oneOf[1]', 'TestObjectDTO.allOf[1]' or 'TestObjectDTO.anyOf[1].testField' | string | |
| schemaDiff | Changes for the parameter schema Detailed OpenAPI Specification Examples | {type: "number"} | OpenAPISchema | |
| objectDiff | Changes for the parameter itself | { required: true } | {name?: string; in?: 'query' / 'header' / 'path' / 'cookie'; required?: boolean;} | |
| patchMethod | Method for applying changes specified in objectDiff and schemaDiff. More about differences between merge and deepmerge methods | "merge" | "merge" \ "deepmerge" | "merge" |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-parameter-schema",
config: {
endpointDescriptor: 'GET /api/list', // specify the endpoint to modify
parameterDescriptor: {
name: 'test', // specify parameter name
in: 'query', // specify that parameter is in query
},
schemaDiff: {
enum: ['foo', 'bar'], // add enum to parameter
}
},
}
// ... other rules
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-parameter-schema",
config: {
endpointDescriptor: 'GET /api/list', // specify the endpoint to modify
parameterDescriptor: {
name: 'test', // specify parameter name
in: 'query', // specify that parameter is in query
},
schemaDiff: {
type: 'string', // change parameter type to string
enum: ['foo', 'bar'], // add enum to parameter
},
objectDiff: {
name: 'newTest',
in: 'query',
required: true, // make parameter required
},
patchMethod: 'deepmerge' // use deepmerge method for deep merging changes
},
}
// ... other rules
]
}
`

More details about rule patch-endpoint-parameter-schema

----------------------

$3

Rule for modifying the request body schema in OpenAPI specification. Allows to modify the request schema for a specified endpoint.

#### Config

| Parameter | Description | Example | Type | Default |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|-----------|
| endpointDescriptor | [required] Specifies which endpoint's request parameter schema should be modified. | 'GET /api/list' | string \ { path: string; method: string } | |
| contentType | Specifies which request type (content-type) of the endpoint should be modified. If not specified, all request types will be modified. | 'application/json' | string | |
| correction | Path to the field in the schema for modification | "name" | string | - |
| schemaDiff | [required] Changes to apply to the schema. Detailed examples of OpenAPI specifications | {type: "number"} | OpenAPISchema | |
| patchMethod | Method for applying changes Learn more about differences between merge and deepmerge methods | "merge" | "merge" \ "deepmerge" | "merge" |

Configuration examples:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-request-body-schema",
config: {
endpointDescriptor: 'POST /api/order', // specify the endpoint to modify
correction: "status", // specify path to status field in request body
schemaDiff: {
enum: ['foo', 'bar'], // add enum to status field
},
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-request-body-schema",
config: {
endpointDescriptor: 'POST /api/order', // specify the endpoint to modify
contentType: "application/json", // specify content type to apply changes to
schemaDiff: {
properties: {
testField: {
type: 'number', // change testField type to number
},
},
},
patchMethod: "deepmerge" // use deepmerge method for deep merging changes
},
}
// ... other rules
]
}
`

or

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-request-body-schema",
config: {
endpointDescriptor: 'POST /api/orders',
correction: '[].status',
schemaDiff: {
enum: ['foo', 'bar'],
},
patchMethod: "deepmerge"
},
}
// ... other rules
]
}
`

More details about rule patch-endpoint-request-body-schema

----------------------

$3

The rule allows modifying the response schema for endpoints in the OpenAPI specification.

#### Config

| Parameter | Description | Example | Type | Default |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-----------|
| endpointDescriptor | [required] Specifies which endpoint's response schema should be modified. | 'GET /api/list' | string \ { path: string; method: string } | |
| correction | Path to the schema property for modification | "status" | string | - |
| code | Specifies which response status code to apply the change to. If not specified, will be applied to the first 2xx response. | 200 | number | |
| contentType | Specifies which response type (content-type) of the endpoint to apply the change to. If not specified, all response types will be modified. | 'application/json' | string | |
| schemaDiff | [required] Required changes in OpenAPI format. Detailed OpenAPI specification examples | {type: "number"} | OpenAPISchema | |
| patchMethod | Method for applying changes Learn more about differences between merge and deepmerge methods | "merge" | "merge" \ "deepmerge" | "merge" |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-response-schema",
config: {
endpointDescriptor: 'GET /api/list', // specify the endpoint to modify
correction: '[].status', // specify path to status field in response array
schemaDiff: {
enum: ['foo', 'bar'], // add enum to status field
},
},
}
// ... other rules
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "patch-endpoint-response-schema",
config: {
endpointDescriptor: 'GET /api/list', // specify the endpoint to modify
correction: '[].status', // specify path to status field in response array
code: 200, // specify response code to apply changes to
contentType: 'application/json', // specify content type to apply changes to
schemaDiff: {
enum: ['foo', 'bar'], // add enum to status field
},
patchMethod: 'deepmerge' // use deepmerge method for deep merging changes
},
}
// ... other rules
]
}
`

More details about rule patch-endpoint-response-schema

----------------------

$3

The rule allows modifying the entire endpoint schema in the OpenAPI specification. Unlike other patching rules that work with individual parts of the endpoint (parameters, request body, responses), this rule can modify the entire endpoint structure, including all its components.

#### Config

| Parameter | Description | Example | Typing | Default |
|--------------------------------|--------------------------------------------------------|---------|------------|---------------|
| endpointDescriptor | [required] Endpoint description for patching | { path: "/pets", method: "get" } | { path: string, method: string } | - |
| endpointDescriptorCorrection | Path to a specific field in the endpoint schema for patching | "responses.200.content.application/json.schema" | string | - |
| schemaDiff | [required] Required changes in OpenAPI format. Detailed OpenAPI specification examples | { type: "object", properties: { ... } } | OpenAPISchema | - |
| patchMethod | Method for applying changes Learn more about differences between merge and deepmerge methods | "merge" | "merge" \ "deepmerge" | "merge" |

Configuration example:

`js
module.exports = {
pipeline: [
{
rule: "patch-endpoint-schema",
config: {
endpointDescriptor: "GET /pets", // specify the endpoint to modify
patchMethod: "merge", // use merge method to apply changes
schemaDiff: {
"security": [ // add security section to the schema
{
"bearerAuth": []
}
]
}
}
}
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
{
rule: "patch-endpoint-schema",
config: {
patchMethod: 'merge',
endpointDescriptor: "GET /pets",
endpointDescriptorCorrection: 'responses.200.content./.schema',
schemaDiff: {
enum: ['3', '4'],
},
}
}
]
}
`

More details about rule patch-endpoint-schema

----------------------

$3

The rule allows removing deprecated elements from the OpenAPI specification. It can remove deprecated components, endpoints, parameters, and properties, while providing the ability to ignore specific elements and display descriptions of removed elements.

#### Config

| Parameter | Description | Example | Type | Default |
|----------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|-----------|-----------|
| ignoreComponents | [optional] List of components that should not be removed, even if they are marked as deprecated | [{"componentName": "Pet"}] | Array<{ componentName: string }> | [] |
| ignoreEndpoints | [optional] List of endpoints that should not be removed, even if they are marked as deprecated | ["GET /pets"] | Array | [] |
| ignoreEndpointParameters | [optional] List of endpoint parameters that should not be removed, even if they are marked as deprecated | [{"path": "/pets", "method": "get", "name": "limit", "in": "query"}] | Array<{ path: string; method: string; name: string; in: "query" \ "path" \ "header" \ "cookie" }> | [] |
| showDeprecatedDescriptions | [optional] Whether to show descriptions of removed deprecated elements in logs, useful for explaining what should be used instead | true | boolean | false |

> [!IMPORTANT]
> Only local $refs of the file are considered, in the format: #/...

Configuration example:

`js
module.exports = {
pipeline: [
{
rule: "remove-deprecated",
config: {},
}
]
}
`

Example of a more detailed configuration:

`js
module.exports = {
pipeline: [
{
rule: "remove-deprecated",
config: {
ignoreComponents: [
{ componentName: "Pet" } // save the Pet component even if it is marked as deprecated
],
ignoreEndpoints: [
{ path: "/pets", method: "get" } // save GET /pets even if it is marked as deprecated
],
ignoreEndpointParameters: [
{ path: "/pets", method: "get", name: "limit", in: "query" } // keep the limit parameter in GET /pets even if it is marked as deprecated
],
showDeprecatedDescriptions: true // output descriptions of deleted deprecated items to the console
},
}
]
}
`

More details about rule remove-deprecated

----------------------

$3

Removes the maxItems property from all schemas in the OpenAPI specification.

#### Config

| Parameter | Description | Example | Type | Default |
| --------- | ----------- | ------- | ---- | ------- |
| showUnusedWarning | [optional] Show a warning if no schemas with maxItems are found | true | boolean | false |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-max-items",
config: {} // remove maxItems property from all schemas, don't show warnings
}
// ... other rules
]
}
`

Example of more detailed configuration:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-max-items",
config: {
showUnusedWarning: true // show warning if no schemas with maxItems are found in the specification
}
}
// ... other rules
]
}
`

More details about rule remove-max-items

----------------------

$3

Removes the minItems property from all schemas in the OpenAPI specification.

#### Config

| Parameter | Description | Example | Type | Default |
| --------- | ----------- | ------- | ---- | ------- |
| showUnusedWarning | [optional] Show a warning if no schemas with minItems are found | true | boolean | false |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-min-items",
config: {} // remove minItems property from all schemas, don't show warnings
}
// ... other rules
]
}
`

Example of more detailed configuration:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-min-items",
config: {
showUnusedWarning: true // show warning if no schemas with minItems are found in the specification
}
}
// ... other rules
]
}
`

More details about rule remove-min-items

----------------------

$3

Removes operationId from all operations in the OpenAPI specification, except those specified in the ignore list

#### Config

| Parameter | Description | Example | Type | Default |
| -------- |-----------------------------------|----------------------------|------------------------|-----------|
| ignore | [optional] List of operationIds to ignore | ["getPets", "createPet"] | string[] | [] |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-operation-id",
config: {} // remove all operationId attributes from endpoints
}
// ... other rules
]
}
`

Example of more detailed configuration:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-operation-id",
config: {
ignore: ["getPets", "createPet"], // keep operationId for this endpoint
},
}
// ... other rules
]
}
`

More details about rule remove-operation-id

----------------------

$3

Removes a parameter from an endpoint in the OpenAPI specification

#### Config

| Parameter | Description | Example | Typing | Default |
| -------- |-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|------------------------|-----------|
| endpointDescriptor | [required] Description of the endpoint from which to remove the parameter | "GET /pets" | string \ { path: string; method: string } | - |
| parameterDescriptor | [required] Description of the parameter to remove. In the in parameter, you can specify: "query", "path", "header", "cookie". | {"name": "petId", "in": "path"} | { name: string; in: "query" \ "path" \ "header" \ "cookie" } | - |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-parameter",
config: {
endpointDescriptor: "GET /pets/{petId}", // specify the endpoint from which to remove the parameter
parameterDescriptor: {
name: "version", // specify the name of the parameter to be deleted
in: "query" // specify the parameter location (query parameter)
}
},
}
// ... other rules
]
}
`

More details about rule remove-parameter

----------------------

$3

Removes unused components from the OpenAPI specification. The rule analyzes all component references in the document and removes those that are not used anywhere.

#### Config

| Parameter | Description | Example | Type | Default |
| -------- |-----------------------------------|-------------------|------------------------|-----------|
| ignore | [optional] List of components or regular expressions to ignore during removal | ["NotFoundDTO", "/^Error.*/"] | Array | [] |
| printDeletedComponents | [optional] If true, prints the list of deleted components to console | true | boolean | false |

Configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-unused-components",
config: {},
}
// ... other rules
]
}
`

More detailed configuration example:

`js
module.exports = {
pipeline: [
// ... other rules
{
rule: "remove-unused-components",
config: {
ignore: [
"NotFoundDTO",
/^Error.*/, // ignore all components starting with Error
/.*Response$/ // ignore all components ending with Response
],
printDeletedComponents: true // print list of deleted components to console
},
}
// ... other rules
]
}
`

More details about rule remove-unused-components

FAQ

- Why are $ref modifications dangerous? Because it means that $ref refers to a common part of the schema, and its modification may lead to implicit changes in another part of the specification where $ref is reused, and such a bug will be extremely difficult to catch.

Usage Examples

In the examples` directory, you can find various examples of using the package:

- example-cli-generate-api-types - Example of generating API types using CLI
- example-cli-openapi-json - Example of working with OpenAPI JSON format via CLI
- example-cli-openapi-yaml - Example of working with OpenAPI YAML format via CLI
- example-cli-openapi-yaml-to-json - Example of converting YAML to JSON format
- example-cli-simple-generate-api-types - Simple example of generating API types
- example-cli-simple-json-config - Example of using JSON configuration
- example-cli-simple-npx - Example of using via npx
- example-package-openapi-yaml - Example of programmatic package usage