@e22m4u/js-openapi 0.0.5

package/.c8rc

@@ -0,0 +1,9 @@
+{
+  "all": true,
+  "include": [
+    "src/**/*.js"
+  ],
+  "exclude": [
+    "src/**/*.spec.js"
+  ]
+}

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+max_line_length = 80

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+npm run lint:fix
+npm run format
+npm run test
+npm run build:cjs
+
+git add -A

package/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "extension": ["js"],
+  "spec": "src/**/*.spec.js"
+}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "bracketSpacing": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2025 Mikhail Evstropov <e22m4u@yandex.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,510 @@
+## @e22m4u/js-openapi
+
+JavaScript модуль для создания
+[OpenAPI Документа 3.1.0](https://spec.openapis.org/oas/v3.1.0)
+
+## Содержание
+
+- [Установка](#установка)
+- [Базовый пример](#базовый-пример)
+- [Работа с компонентами](#работа-с-компонентами)
+- [Содержимое запросов и ответов](#содержимое-запросов-и-ответов)
+- [Группировка маршрутов](#группировка-маршрутов)
+- [Проверка данных](#проверка-данных)
+- [Тесты](#тесты)
+- [Лицензия](#лицензия)
+
+## Установка
+
+```bash
+npm install @e22m4u/js-openapi
+```
+
+Модуль поддерживает ESM и CommonJS стандарты.
+
+*ESM*
+
+```js
+import {OADocumentBuilder} from '@e22m4u/js-openapi';
+```
+
+*CommonJS*
+
+```js
+const {OADocumentBuilder} = require('@e22m4u/js-openapi');
+```
+
+## Базовый пример
+
+Создание экземпляра сборщика.
+
+```js
+import {OADocumentBuilder} from '@e22m4u/js-openapi';
+
+const builder = new OADocumentBuilder({
+  info: {
+    title: 'My Simple API',
+    version: '0.0.1',
+  },
+});
+```
+
+Определение операции.
+
+```js
+import {OAOperationMethod} from '@e22m4u/js-openapi';
+
+builder.defineOperation({
+  path: '/status',
+  method: OAOperationMethod.GET,
+  operation: {
+    summary: 'Get server status',
+    responses: {
+      200: {
+        description: 'Server works fine',
+      },
+    },
+  },
+});
+```
+
+Формирование JSON документа.
+
+```js
+const jsonDoc = builder.buildJson(2);
+// первый аргумент указывает количество пробелов
+// для каждого уровня вложенности, и может быть
+// опущен в целях экономии размера документа
+
+console.log(jsonDoc);
+// {
+//   "openapi": "3.1.0",
+//   "info": {
+//     "title": "My Simple API",
+//     "version": "0.0.1"
+//   },
+//   "paths": {
+//     "/status": {
+//       "get": {
+//         "summary": "Get server status",
+//         "responses": {
+//           "200": {
+//             "description": "Server works fine"
+//           }
+//         }
+//       }
+//     }
+//   }
+// }
+```
+
+## Работа с компонентами
+
+Регистрация компонента схемы.
+
+```js
+import {OADataType, OAOperationMethod} from '@e22m4u/js-openapi';
+
+builder.defineSchemaComponent({
+  name: 'User', // <= имя нового компонента
+  schema: {
+    type: OADataType.OBJECT,
+    properties: {
+      id: {
+        type: OADataType.STRING,
+        format: 'uuid',
+      },
+      email: {
+        type: OADataType.STRING,
+        format: 'email',
+      },
+    },
+    required: ['id', 'email'],
+  },
+});
+```
+
+Регистрация компонента параметра.
+
+```js
+import {OADataType, OAParameterLocation} from '@e22m4u/js-openapi';
+
+builder.defineParameterComponent({
+  name: 'idParam', // <= имя нового компонента
+  parameter: {
+    name: 'id',
+    in: OAParameterLocation.PATH,
+    description: 'Identifier',
+    required: true,
+  },
+});
+```
+
+Использование зарегистрированного имени компонента.
+
+```js
+import {
+  oaSchemaRef,
+  OAMediaType,
+  oaParameterRef,
+  OAOperationMethod,
+} from '@e22m4u/js-openapi';
+
+// GET /users/{id}
+builder.defineOperation({
+  path: '/users/{id}',
+  method: OAOperationMethod.GET,
+  operation: {
+    parameters: [
+      oaParameterRef('idParam'), // <= ссылка на параметр
+      // утилита "oaParameterRef" создаст объект-ссылку:
+      // {"$ref": "#/components/parameters/idParam"}
+    ],
+    responses: {
+      200: {
+        description: 'User found',
+        content: {
+          [OAMediaType.APPLICATION_JSON]: {
+            schema: oaSchemaRef('User'), // <= ссылка на схему
+            // утилита "oaSchemaRef" создаст объект-ссылку:
+            // {"$ref": "#/components/schemas/User"}
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+## Содержимое запросов и ответов
+
+Определение тела запроса для операции.
+
+```js
+import {OADataType, OAMediaType, OAOperationMethod} from '@e22m4u/js-openapi';
+
+// POST /users
+builder.defineOperation({
+  path: '/users',
+  method: OAOperationMethod.POST,
+  operation: {
+    summary: 'Create a new user',
+    // тело запроса
+    requestBody: {
+      description: 'Data for the new user',
+      required: true,
+      content: {
+        [OAMediaType.APPLICATION_JSON]: {
+          // схема тела
+          schema: {
+            type: OADataType.OBJECT,
+            properties: {
+              email: {
+                type: OADataType.STRING,
+                format: 'email',
+              },
+              password: {
+                type: OADataType.STRING,
+              },
+            },
+            required: ['email', 'password'],
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+Определение тела ответа для операции.
+
+```js
+import {OADataType, OAMediaType, OAOperationMethod} from '@e22m4u/js-openapi';
+
+// GET /status
+builder.defineOperation({
+  path: '/status',
+  method: OAOperationMethod.GET,
+  operation: {
+    summary: 'Get server status',
+    responses: {
+      // успешный ответ
+      200: {
+        description: 'Server works fine',
+        content: {
+          [OAMediaType.APPLICATION_JSON]: {
+            // схема ответа
+            schema: {
+              type: OADataType.OBJECT,
+              properties: {
+                status: {
+                  type: OADataType.STRING,
+                  example: 'ok',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+Определение компонента схемы для использования в следующем примере.
+
+```js
+import {OADataType} from '@e22m4u/js-openapi';
+
+builder.defineSchemaComponent({
+  name: 'UserInput', // <= имя нового компонента
+  schema: {
+    type: OADataType.OBJECT,
+    properties: {
+      email: {
+        type: OADataType.STRING,
+        format: 'email',
+      },
+      password: {
+        type: OADataType.STRING,
+      },
+    },
+    required: ['email', 'password'],
+  },
+});
+```
+
+Определение содержания запроса и ответа с использованием ссылок.
+
+```js
+import {oaSchemaRef, OAMediaType, OAOperationMethod} from '@e22m4u/js-openapi';
+
+// POST /users
+builder.defineOperation({
+  path: '/users',
+  method: OAOperationMethod.POST,
+  operation: {
+    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('User'), // <= ссылка на схему
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+## Группировка маршрутов
+
+Создание области с общим префиксом пути и тегом.
+
+```js
+import {OAOperationMethod} from '@e22m4u/js-openapi';
+
+// создание области /users
+const usersScope = builder.createScope({
+  pathPrefix: '/users',
+  tags: ['User'], // опционально
+});
+
+// маршрут GET /users/{id}
+usersScope.defineOperation({
+  path: '/{id}',
+  method: OAOperationMethod.GET,
+  operation: {
+    summary: 'Find user',
+    responses: {
+      200: {
+        description: 'User found',
+      },
+    },
+  },
+});
+
+// маршрут DELETE /users/{id}
+usersScope.defineOperation({
+  path: '/{id}',
+  method: OAOperationMethod.DELETE,
+  operation: {
+    summary: 'Delete user',
+    responses: {
+      200: {
+        description: 'User deleted',
+      },
+    },
+  },
+});
+```
+
+Создание вложенных областей для комбинирования маршрутов.
+
+```js
+import {OAOperationMethod} from '@e22m4u/js-openapi';
+
+// область "/api/v1"
+const v1Scope = builder.createScope({
+  pathPrefix: '/api/v1',
+});
+
+// область "/api/v1/admin"
+const adminScope = v1Scope.createScope({
+  pathPrefix: '/admin',
+});
+
+// DELETE /api/v1/admin/users/{id}
+adminScope.defineOperation({
+  path: '/users/{id}',
+  method: OAOperationMethod.DELETE,
+  operation: {
+    summary: 'Delete user',
+    responses: {
+      200: {
+        description: 'User deleted',
+      },
+    },
+  },
+});
+```
+
+## Проверка данных
+
+Проверка данных с помощью объекта схемы.
+
+```js
+import {OADataType, validateDataWithOpenApiSchema} from '@e22m4u/js-openapi';
+
+const schema = {
+  type: OADataType.OBJECT,
+  properties: {
+    name: {type: OADataType.STRING},
+    age: {type: OADataType.NUMBER},
+  },
+};
+
+const data = {
+  name: 'Fedor',
+  age: 'invalid',
+};
+
+validateDataWithOpenApiSchema(data, schema);
+// OADataValidationError:
+// Value at "/age" must be Number, but String was given.
+```
+
+Отключение выброса ошибки для ручной обработки результата.
+
+```js
+const result = validateDataWithOpenApiSchema(data, schema, {
+  silent: true, // <= бесшумный режим
+});
+console.log(result);
+// {
+//   isValid: false,
+//   value: 'invalid',
+//   valueUri: '/age',
+//   schemaUri: '/properties/age',
+//   reason: 'Value at "/age" must be Number, but String was given.',
+// }
+```
+
+Проверка данных с приведением типов.
+
+```js
+import {OADataType, validateDataWithOpenApiSchema} from '@e22m4u/js-openapi';
+
+const schema = {
+  type: OADataType.OBJECT,
+  properties: {
+    phone: {type: OADataType.STRING},
+    quantity: {type: OADataType.INTEGER},
+    featured: {type: OADataType.BOOLEAN},
+  },
+};
+
+const data = {
+  phone: 88005553535, // приводится к строке
+  quantity: '3',      // приводится к целому числу
+  featured: 'true'    // приводится к логическому значению
+};
+
+const result = validateDataWithOpenApiSchema(data, schema, {
+  coerceTypes: true, // <= приведение типов
+});
+console.log(result);
+// {
+//   isValid: true,
+//   value: {
+//     phone: '88005553535',
+//     quantity: 3,
+//     featured: true
+//   }
+// }
+```
+
+Проверка данных с разбором JSON.
+
+```js
+import {OADataType, validateDataWithOpenApiSchema} from '@e22m4u/js-openapi';
+
+const schema = {
+  type: OADataType.ARRAY,
+  prefixItems: [
+    {type: OADataType.INTEGER},
+    {type: OADataType.BOOLEAN},
+    {type: OADataType.ARRAY},
+    {type: OADataType.OBJECT},
+  ],
+};
+
+const data = [
+  '123',       // приводится к целому числу
+  'true',      // приводится к логическому значению
+  '[1, 2, 3]', // приводится к массиву
+  '{"where": {"id": 10}, "include": "user"}', // приводится к объекту
+];
+
+const result = validateDataWithOpenApiSchema(data, schema, {
+  parseJson: true, // <= разбор JSON
+});
+console.log(result);
+// {
+//   isValid: true,
+//   value: [
+//     123,
+//     true,
+//     [1, 2, 3],
+//     {
+//       where: {
+//         id: 10,
+//       },
+//       include: 'user'
+//     }
+//   ]
+// }
+```
+
+## Тесты
+
+```bash
+npm run test
+```
+
+## Лицензия
+
+MIT

package/build-cjs.js

@@ -0,0 +1,16 @@
+import * as esbuild from 'esbuild';
+import packageJson from './package.json' with {type: 'json'};
+
+await esbuild.build({
+  entryPoints: ['src/index.js'],
+  outfile: 'dist/cjs/index.cjs',
+  format: 'cjs',
+  platform: 'node',
+  target: ['node18'],
+  bundle: true,
+  keepNames: true,
+  external: [
+    ...Object.keys(packageJson.peerDependencies || {}),
+    ...Object.keys(packageJson.dependencies || {}),
+  ],
+});