## @e22m4u/js-trie-router-openapi

Модуль OpenAPI документации для
[@e22m4u/js-trie-router](https://www.npmjs.com/package/@e22m4u/js-trie-router)

## Содержание

- [Установка](#установка)
- [Использование](#использование)
- [Тесты](#тесты)
- [Лицензия](#лицензия)

## Установка

```bash
npm install @e22m4u/js-trie-router-openapi
```

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

*ESM*

```js
import {TrieRouterOpenApi} from '@e22m4u/js-trie-router-openapi';
```

*CommonJS*

```js
const {TrieRouterOpenApi} = require('@e22m4u/js-trie-router-openapi');
```

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

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

```js
import {TrieRouter} from '@e22m4u/js-trie-router';
import {TrieRouterOpenApi} from '@e22m4u/js-trie-router-openapi';

// создание маршрутизатора
const router = new TrieRouter();

// подключение расширения
router.useService(TrieRouterOpenApi, {
  info: {
    title: 'API Documentation',
    version: '0.0.1',
  },
});
```

Определение компонентов схем, используемых в следующих примерах.

```js
import {OADataType, OADocumentBuilder} from '@e22m4u/js-trie-router-openapi';

const builder = router.getService(OADocumentBuilder);

// данные нового пользователя
builder.defineSchemaComponent({
  name: 'UserInput', // <= имя новой схемы
  schema: {
    type: OADataType.OBJECT,
    properties: {
      email: {
        type: OADataType.STRING,
        format: 'email',
      },
      password: {
        type: OADataType.STRING,
      },
    },
    required: ['email', 'password'],
  },
});

// публичные данные пользователя
builder.defineSchemaComponent({
  name: 'UserOutput', // <= имя новой схемы
  schema: {
    type: OADataType.OBJECT,
    properties: {
      id: {
        type: OADataType.STRING,
        format: 'uuid',
      },
      email: {
        type: OADataType.STRING,
        format: 'email',
      },
    },
    required: ['id', 'password'],
  },
});
```

Определение метаданных маршрута.

```js
import {HttpMethod} from '@e22m4u/js-trie-router';
import {oaSchemaRef, OAMediaType} from '@e22m4u/js-trie-router-openapi';

router.defineRoute({
  method: HttpMethod.POST,
  path: '/users',
  meta: {
    openApi: {
      summary: 'Create a new user',
      // тело запроса
      requestBody: {
        description: 'Data for the new user',
        required: true,
        content: {
          [OAMediaType.APPLICATION_JSON]: {
            schema: oaSchemaRef('UserInput'),
            // ссылка на схему ^^^
          },
        },
      },
      responses: {
        // успешный ответ
        201: {
          description: 'User created',
          content: {
            [OAMediaType.APPLICATION_JSON]: {
              schema: oaSchemaRef('UserOutput'),
              // ссылка на схему ^^^
            },
          },
        },
      },
    },
  },
  handler: (ctx) => {
    // ...
  },
});
```

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

```js
import {OADocumentBuilder} from '@e22m4u/js-trie-router-openapi';

const builder = router.getService(OADocumentBuilder);

const jsonDoc = builder.buildJson(2);
// первый аргумент указывает количество пробелов
// для каждого уровня вложенности, и может быть
// опущен в целях экономии размера документа

console.log(jsonDoc);
// {
//   "openapi": "3.1.0",
//   "info": {
//     "title": "API Documentation",
//     "version": "0.0.1"
//   },
//   "paths": {
//     "/users": {
//       "post": {
//         "summary": "Create a new user",
//         "requestBody": {
//           "description": "Data for the new user",
//           "required": true,
//           "content": {
//             "application/json": {
//               "schema": {
//                 "$ref": "#/components/schemas/UserInput"
//               }
//             }
//           }
//         },
//         "responses": {
//           "201": {
//             "description": "User created",
//             "content": {
//               "application/json": {
//                 "schema": {
//                   "$ref": "#/components/schemas/UserOutput"
//                 }
//               }
//             }
//           }
//         }
//       }
//     }
//   },
//   "components": {
//     "schemas": {
//       "UserInput": { ... },
//       "UserOutput": { ... }
//     }
//   }
// }
```

## Тесты

```bash
npm run test
```

## Лицензия

MIT