Skip to content

Latest commit

 

History

History
203 lines (169 loc) · 7.8 KB

README.md

File metadata and controls

203 lines (169 loc) · 7.8 KB

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

patch-endpoint-parameter-schema

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

Configuration

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:

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:

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
    ]
}

If you need to modify multiple specifications, you can use this rule multiple times in the overall configuration pipeline.

Motivation

1. Modifying Endpoint Parameter Schema

Practical example:

In the openapi.yaml file, the endpoint parameter looks like this:

paths:
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          schema:
            type: string

We need to modify the parameter schema by adding UUID format and making it required.

In the configuration file openapi-modifier-config.js, we add the patch-endpoint-parameter-schema rule:

module.exports = {
    pipeline: [
        {
            rule: "patch-endpoint-parameter-schema",
            config: {
                endpointDescriptor: "GET /pets/{petId}",
                parameterDescriptor: {
                    name: "petId",
                    in: "path"
                },
                schemaDiff: {
                    format: "uuid"
                },
                objectDiff: {
                    required: true
                }
            }
        }
    ]
}

After applying the rule, the openapi.yaml file looks like this:

paths:
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: string
            format: uuid

2. Modifying Parameter Component Schema

Practical example:

In the openapi.yaml file, the parameter component looks like this:

components:
  parameters:
    PetIdParam:
      name: petId
      in: path
      schema:
        type: string

We need to modify the parameter component schema by adding UUID format.

In the configuration file openapi-modifier-config.js, we add the patch-endpoint-parameter-schema rule:

module.exports = {
    pipeline: [
        {
            rule: "patch-endpoint-parameter-schema",
            config: {
                parameterDescriptor: {
                    name: "petId",
                    in: "path"
                },
                schemaDiff: {
                    format: "uuid"
                }
            }
        }
    ]
}

After applying the rule, the openapi.yaml file looks like this:

components:
  parameters:
    PetIdParam:
      name: petId
      in: path
      schema:
        type: string
        format: uuid

Important Notes

  • The rule skips parameters defined via references ($ref)
  • If the specified parameter or endpoint is not found, the rule outputs a warning for timely updating of the openapi-modifier configuration
  • Changes are applied atomically - either all changes are successful, or the specification remains unchanged

Useful Links