Skip to content

Latest commit

 

History

History
204 lines (168 loc) · 8.48 KB

README-ru.md

File metadata and controls

204 lines (168 loc) · 8.48 KB

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

patch-component-schema

Правило позволяет модифицировать схему компонента в OpenAPI спецификации.

Конфигурация

Параметр Описание Пример Типизация Дефолтное
descriptor [обязательный] Описание компонента для модификации. Подробнее про различия между простым и объектным дескриптором компонента с коррекцией "Pet.name" или {"componentName": "Pet", "correction": "properties.name"} string \ { componentName: string; correction: string } -
patchMethod Метод применения патча. Подробнее про различия между методами merge и deepmerge "merge" "merge" \ "deepmerge" "merge"
schemaDiff [обязательный] Схема для патча. Подробные примеры спецификаций для OpenAPI {"type": "string", "description": "New description"} OpenAPISchema -

Important

Тонкости задачния параметра descriptor:

  • не предусмотрен переход по $ref'ам. Потому что может вызвать не преднамеренное изменение в общих компонентах, и тем самым создать не ожиданное изменение в другом месте спецификации. В таком случае лучше модифицировать напрямую ту сущность на которую ссылается $ref;
  • если необходим переход по элементам массива - нужно доуточнение в descriptor (соотвтественно []), например, TestSchemaDTO[].test
  • если необходим переход по oneOf, allOf, anyOf нужно доуточнение в descriptor (соотвтественно oneOf[{number}], allOf[{number}] или anyOf[{number}]), например, TestObjectDTO.oneOf[1].TestSchemaDTO, TestObjectDTO.allOf[1].TestSchemaDTO или TestObjectDTO.anyOf[1].TestSchemaDTO;

Пример конфигурации:

module.exports = {
    pipeline: [
        // ... other rules
        {
            rule: "patch-component-schema",
            config: {
                descriptor: 'TestDTO', // указываем компонент, который нужно изменить
                schemaDiff: {
                    type: 'string', // меняем тип компонента на string
                },
            },
        }
        // ... other rules
    ]
}

Пример более детальной конфигурации:

module.exports = {
    pipeline: [
        // ... other rules
        {
            rule: "patch-component-schema",
            config: {
                descriptor: 'TestObjectDTO.oneOf[0].TestArraySchemaDTO[]', // указываем путь к компоненту в сложной структуре
                schemaDiff: {
                    type: 'string', // меняем тип компонента на string
                    enum: ['foo', 'bar'], // добавляем enum к компоненту
                },
                patchMethod: 'deepmerge', // используем метод deepmerge для глубокого слияния изменений
            },
        }
        // ... other rules
    ]
}

Если необходимо изменить несколько спецификаций, вы можете использовать несколько раз данное правило в общем пайлайне конфигурации.

Мотивация

1. Необходимо обновить описание конкретного свойства в схеме компонента

Практический пример:

В файле openapi.yaml схема компонента выглядит так:

components:
  schemas:
    Pet:
      type: object
      properties:
        status:
          type: string
          enum:
            - status1
            - status2

Нужно обновить описание свойства type, расширив enum дополнительными значениями.

В файле конфигурации openapi-modifier-config.js добавляем правило patch-component-schema:

module.exports = {
    pipeline: [
        {
            rule: "patch-component-schema",
            config: {
                descriptor: "Pet.status",
                patchMethod: "deepmerge",
                schemaDiff: {
                    enum: ['status3', 'status4'],
                }
            },
        }
    ]
}

После применения правила, файл openapi.yaml выглядит так:

components:
  schemas:
    Pet:
      type: object
      properties:
        status:
          type: string
          enum:
            - status1
            - status2
            - status3
            - status4

2. Необходимо полностью заменить схему компонента

Практический пример:

В файле openapi.yaml схема компонента выглядит так:

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string

Нужно полностью заменить схему компонента.

В файле конфигурации openapi-modifier-config.js добавляем правило patch-component-schema:

module.exports = {
    pipeline: [
        {
            rule: "patch-component-schema",
            config: {
                descriptor: {
                    componentName: "Pet"
                },
                patchMethod: "merge",
                schemaDiff: {
                    type: "object",
                    properties: {
                        id: {
                            type: "string",
                            description: "Pet id"
                        },
                        age: {
                            type: "integer",
                            description: "Pet age"
                        }
                    }
                }
            },
        }
    ]
}

После применения правила, файл openapi.yaml выглядит так:

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: string
          description: Pet id
        age:
          type: integer
          description: Pet age

Важные замечания

Полезные ссылки