js-trie-router-openapi

@e22m4u/js-trie-router-openapi

Модуль создания OpenAPI документа для @e22m4u/js-trie-router

• Генерация OpenAPI 3.1 документа согласно определению маршрутов.
• Валидация OpenAPI схем и компонентов в момент определения.
• Поддержка ссылок
  $ref
  на зарегистрированные компоненты.

Содержание

• Установка
• Использование
• Компоненты и ссылки
• Настройки
• Тесты
• Лицензия

Установка

Модуль поддерживает ESM и CommonJS стандарты.

ESM

CommonJS

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

Подключение модуля к маршрутизатору.

Быстрое добавление маршрута в документацию.

Определение компонента схемы.

Использование компонентов в спецификации маршрута.

Отдача документации через маршрутизатор.

Формирование JSON документа.

Компоненты и ссылки

OpenAPI позволяет выносить повторяющиеся участки спецификации в общий набор компонентов. Это делает определения маршрутов и итоговый документ компактными.

Для регистрации компонентов в классе

предусмотрены специальные методы, а для формирования ссылок на компоненты используются функции-утилиты.

Поддерживаемые типы компонентов

Ниже представлен список доступных типов компонентов. Для каждого из них указан метод регистрации в объекте

и соответствующая функция-утилита для создания

$ref

ссылки.

Schema

Метод:

Ссылка:

oaSchemaRef(name)

Parameter

Метод:

Ссылка:

oaParameterRef(name)

Request Body

Метод:

Ссылка:

oaRequestBodyRef(name)

Response

Метод:

Ссылка:

oaResponseRef(name)

Security Scheme

Метод:

Ссылка:

oaSecuritySchemeRef(name)

Example

Метод:

Ссылка:

oaExampleRef(name)

Link

Метод:

Ссылка:

oaLinkRef(name)

Callback

Метод:

Ссылка:

oaCallbackRef(name)

Path Item

Метод:

Ссылка:

oaPathItemRef(name)

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

Если в маршрутах используется определенный параметр и стандартный ответ, то их можно зарегистрировать в качестве переиспользуемых компонентов. В примере ниже определяется компонент параметра

и компонент ответа сервера

404 Not Found

.

Теперь можно ссылаться на эти компоненты при определении маршрутов, используя специальные утилиты, которые автоматически генерируют объект ссылки.

Настройки

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

Параметры

• document

document

Тип:

По умолчанию:

{info: {title: 'API Documentation', version: '0.0.1'}}

Позволяет задать базовую структуру OpenAPI документа при инициализации расширения. Сюда передаются корневые настройки спецификации, список серверов, глобальные требования безопасности и заранее подготовленные компоненты.

Тесты

Лицензия

MIT