При помощи правила можно убрать из сущности поле, и сгенерировать типизацию без нее, и если запустить проверку типизации в проекте TS поможет найти все места использования.

{
    "rule": "patch-schemas"
}

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

[!IMPORTANT]
Поддерживает OpenAPI 3.1, 3.0. Мы не проверяли поддержку OpenAPI 2, так как формат является устаревшим и рекомендуем мигрировать вашу документацию на OpenAPI 3.0.

Демонстрация использования

Например имеем входной файл спецификации/документации api от бекенд разработчиков. Например, скачен через curl cli из github.

Пишем файл конфигурации, описывающий все что нужно поменять в исходной спецификации/документации с пояснительными комментариями:

const config: ConfigT = {
    pipeline: [
        // JIRA-10207 - new feature API for epic JIRA-232
        {
            rule: 'merge-openapi-spec',
            config: {
                path: 'input/feature-openapi-JIRA-232.yaml',
            },
        },

        // ...

        // JIRA-10212 - wrong docs, waiting JIRABACKEND-8752
        {
            rule: 'patch-schemas',
            config: [
                {
                    descriptor: {
                        type: 'component-schema',
                        componentName: 'Pet',
                    },
                    patchMethod: 'merge',
                    schemaDiff: {
                        properties: {
                            id: {
                                type: 'string',
                                format: 'uuid',
                            },
                        },
                    },
                },
            ],
        },

        // ...

        // JIRA-11236 - removed deprecated endpoint, waiting JIRABACKEND-3641
        {
            rule: 'filter-endpoints',
            config: {
                disabled: [
                    {
                        path: '/v1/pets/{petId}',
                        method: 'delete',
                    },
                ],
            },
        },

        // ...
}

Далее при помощи этого файла конфигурации и cli openapi-modifier, изменяем исходный файл спецификации/документации и получается модифицированная спецификация/документация.

Далее при помощи, к примеру cli dtsgenerator, генерируем из модифицированной спецификации/документаци файл типизации для api, которую уже используем в коде проекта.

Полный код примера

Примеры как можно использовать сгенерированную типизацию для api можно в отдельном репозитории с примерами применения.

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

При помощи npx

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

на примере использования

или при помощи npm

npm i --save-dev openapi-modifier

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

на примере использования

Параметры:

Опция	Описание	Пример	Дефолтное
`input`	[обязательный] входной файл, специфиакция/документация в формате openapi	`input/openapi.yml`
`output`	[обязательный] выходной файл, специфиакция/документация в формате opeanpi	`output/openapi.yml`
`config`	путь до файла конфигурации. Детальное описание конфигурации см. ниже	`openapi-modifier.config.js`	`openapi-modifier.config.(js\ts\json\yaml\yml)`

Демонстрация на примере использования

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

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

Если путь до конфигурации не указан, конфигурации по-умолчанию берется из файла openapi-modifier.config.js относительно директории запуска.

Пример конфигурации в .ts. Наример, назовем файл openapi-modifier.config.ts.

import type { ConfigT } from 'openapi-modifier';

const config: ConfigT = {
  input: './input/openapi.yaml',
  output: './output/openapi.yaml',
  rules: [
    // ... more rules
    {
      name: 'remove-operation-id',
      disabled: true,
    },
    // ... more rules
  ],
};

export default config;

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

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

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

Параметры:

Опция	Описание	Дефолтное
`logger.minLevel`	[обязательный] входной файл, специфиакция/документация в формате openapi
`input`	[обязательный] выходной файл, специфиакция/документация в формате opeanpi
`output`	[обязательный] выходной файл, специфиакция/документация в формате opeanpi
`pipeline`	последовательность применяемых правил модификации к входному файлу. Детальное описание конфигурации см. ниже	`./openapi-modifier.config.js` или `./openapi-modifier.config.ts`

Простой пример конфигурации, например файл openapi-modifier.config.json:

{
  "pipeline": [
    {
      "rule": "remove-operation-id"
    }
  ]
}

Пример использования

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

import { openapiModifier } from 'openapi-modifier';

// ...

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

Демонстрация на примере использования

или используя отдельный файл конфигурации

import { openapiModifier } from 'openapi-modifier';

// ...

await openapiModifier({
  input: 'input/openapi.yml',
  output: 'output/openapi.yml',
  config: 'openapi-modifier.config.ts',
});

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

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

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

index.ts - основной файл с логикой правила - должны быть экспортированы: processor (дефолтный экспорт) и configSchema (именованный экспорт)
index.test.ts - тесты на правило покрывающие все поля конфигурации и примеры их использования
/docs/_description.md - файл с описанием правила
/docs/_motivation.md - файл с описанием мотивации создания правила с примерами (в каких случаях на практике может быть полезно)
/docs/_config.md - файл с описанием конфигурации для правила

Для вывода подробных логов необходимых для отладки см. пункт "Отладка".

Все названия правил должны начинаться с обозначения действия.

Отладка

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

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

DEBUG=openapi-modifier:* openapi-modifier

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

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

Примеры использования

Наиболее приближенный к реальному использованию пример в нем отражено:

модификация openapi.yaml с комментариями для комманды разработчиков (см. файл конфигурации и полученный файл). В нем помечены в каких задачах (JIRA-*) будут исправлены правки, пример ???
способ генерации типизации из API по openapi (см. комманду генерирующую типизацию API)
пост-обработка сгенерированной типизации (см. файл конфигурации и полученный файл типизации API). Проставляется warning для комманды разработки, переименовываются сущности (для удобства использования).

Его конфиг:

Полный код примера

Другие примеры:

Использование как npm пакет в скриптах

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

Больше примеров как можно использовать openapi:

для ...
для ... Подробная статья на habr

simple-text-file-modifier

Подробная документация по cli simple-text-file-modifier

TODO

оптимизация path'ов patch-endpoint-parameter-schema patch-endpoint-request-body-schema patch-endpoint-response-schema patch-endpoint-schema remove-deprecated
поменять логику remove-deprecated: добавить correction для компонентов
причесать README.md правил - 13 штук
причесать главный README.md

FAQs

What is openapi-modifier?

Is openapi-modifier popular?

Is openapi-modifier well maintained?

Package last updated on 30 Sep 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

openapi-modifier