openapi-modifier

[!IMPORTANT]
Поддерживает OpenAPI 3.1, 3.0

TODO что это и мотивация создания

• Бекендер просит проверить используется ли поле в какой-то сущности
• Бекендер просит проверить используется ли параметр в какой-то ручке
• Бекендер создает задачу перестать пользоваться endpoint'ом
• Бекендер написал новое API в разработке но его нет в документации
• Бекендер просит больше не использовать какой-то параметр в endpoint'е
• Не валидное OpenAPI (Например, бекендеры использовали не существующий тип int)
• Нужно оставить знания по модификации (коллеге важно знать почему какое-то поле заблокировано)
• Нужно наблюдать за изменениями API и вовремя корректировать конфиг (убрали использование ручки)

Использование как CLI

openapi-modifier --input=example-1/input.yml --output=example-1/output.yml --config=example-1/openapi-modifier-config.js

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

Можно использовать конфиги в след. расширениях: .js, .yaml, .yml, .json

Пример конфигурации в .js

module.exports = {
  logger: {
    minLevel: 1,
  },
  input: './openapi.yaml',
  output: './openapi.yaml',
  rules: [
    {
      name: 'remove-operation-id',
      disabled: true,
    },
    // ...
  ],
};

Использование как npm пакет/модуль

await openapiModifier({
  input: '',
  output: '',
});

Существующие правила

• remove-operation-id
• remove-min-items
• remove-max-items
• change-endpoints-basepath
• change-content-type
• filter-by-content-type
• filter-endpoints
• patch-schemas
• patch-parameter
• remove-parameter
• merge-openapi-spec
• remove-unused-components

Добавление нового правила

Необходимо в папку rules добавить папку с именем вновь созданного правила с 2 файлами:

• index.ts сама логика правила
• README.md файл с описанием работы правила

Про отладку конкретного правила, см. пункт "Отладка" ниже.

Все названия функций должны начинаться с обозначения действия.

Отладка

Внутри используется для детального логирования debug

Для вывода всех debug логов:

DEBUG=openapi-modifier:* openapi-modifier

Для вывода debug логов по правилу, например по правилу remove-operation-id:

DEBUG=openapi-modifier:rule:remove-operation-id openapi-modifier

TODO Для последовательного преобразования вывод ???