openapi-modifier

OpenAPI описывающий бекендное API далеко не всегда идеальное: содержит ошибки, неточности или какие-то особенности ломают другие инструменты, например, кодогенерацию или генерацию типов.

Данный инструмент предназначен для облегчения работы с OpenAPI - для легкой модификации OpenAPI спецификации и удобного описания/документации изменений для истории/пояснений.

Частые кейсы применения:

При помощи правила можно убрать из сущности поле, и сгенерировать типизацию без нее, и если запустить проверку типизации в проекте 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, которую уже используем в коде проекта.

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

Использование как 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',
});

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

• 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
• remove-deprecated

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

Необходимо в папку 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

TODO описание параметра verbose

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

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

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

Его конфиг:

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

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

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

FAQ

• Чем опасны модификации по ссылкам $ref? Потому что значит что $ref ссылается на общую часть схемы, и ее модификация, возможно, приведет к неявному изменению в другом месте спецификации, где переиспользуется $ref, и такую багу будет крайне сложно отловить.

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

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

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

simple-text-file-modifier

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

TODO

• причесать README.md правил - 13 штук
• причесать главный README.md
• в readme каждого правила добавить ссылку "Назад" (в конец и начало доки)
• проверить ссылки из ошибок на github (якори проверить) и в message factory заменить их
• разделить документацию на ru/en