@e22m4u/js-openapi 0.0.5 → 0.0.7

package/README.md

@@ -1,7 +1,11 @@
 ## @e22m4u/js-openapi
 
 JavaScript модуль для создания
-[OpenAPI Документа 3.1.0](https://spec.openapis.org/oas/v3.1.0)
+[OpenAPI Документа 3.1.2](https://spec.openapis.org/oas/v3.1.2)
+
+Модуль автоматически проверяет структуру документа при определении компонентов
+и операций. Если передать неверное поле, будет выброшена ошибка с указанием
+пути.
 
 ## Содержание
 
@@ -9,8 +13,8 @@ JavaScript модуль для создания
 - [Базовый пример](#базовый-пример)
 - [Работа с компонентами](#работа-с-компонентами)
 - [Содержимое запросов и ответов](#содержимое-запросов-и-ответов)
-- [Группировка маршрутов](#группировка-маршрутов)
-- [Проверка данных](#проверка-данных)
+- [Группировка операций](#группировка-операций)
+- [Константы](#константы)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
 
@@ -68,7 +72,34 @@ builder.defineOperation({
 });
 ```
 
-Формирование JSON документа.
+Сборка документа в виде JavaScript объекта.
+
+```js
+const oaDocumentObject = builder.build();
+
+console.log(oaDocumentObject);
+// {
+//   openapi: '3.1.2',
+//   info: {
+//     title: 'My Simple API',
+//     version: '0.0.1'
+//   },
+//   paths: {
+//     '/status': {
+//       get: {
+//         summary: 'Get server status',
+//         responses: {
+//           '200': {
+//             description: 'Server works fine'
+//           }
+//         }
+//       }
+//     }
+//   }
+// }
+```
+
+Формирование JSON документа (сериализация).
 
 ```js
 const jsonDoc = builder.buildJson(2);
@@ -78,7 +109,7 @@ const jsonDoc = builder.buildJson(2);
 
 console.log(jsonDoc);
 // {
-//   "openapi": "3.1.0",
+//   "openapi": "3.1.2",
 //   "info": {
 //     "title": "My Simple API",
 //     "version": "0.0.1"
@@ -105,22 +136,19 @@ console.log(jsonDoc);
 ```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',
-      },
+builder.defineSchemaComponent('User', {
+  type: OADataType.OBJECT,
+  properties: {
+    id: {
+      type: OADataType.STRING,
+      format: 'uuid',
+    },
+    email: {
+      type: OADataType.STRING,
+      format: 'email',
     },
-    required: ['id', 'email'],
   },
+  required: ['id', 'email'],
 });
 ```
 
@@ -129,14 +157,13 @@ builder.defineSchemaComponent({
 ```js
 import {OADataType, OAParameterLocation} from '@e22m4u/js-openapi';
 
-builder.defineParameterComponent({
-  name: 'idParam', // <= имя нового компонента
-  parameter: {
-    name: 'id',
-    in: OAParameterLocation.PATH,
-    description: 'Identifier',
-    required: true,
-  },
+builder.defineParameterComponent('idParam', {
+  // фактическое имя параметра может
+  // отличаться от имени компонента
+  name: 'id',
+  in: OAParameterLocation.PATH,
+  description: 'Identifier',
+  required: true,
 });
 ```
 
@@ -178,7 +205,7 @@ builder.defineOperation({
 
 ## Содержимое запросов и ответов
 
-Определение тела запроса для операции.
+Определение тела запроса операции.
 
 ```js
 import {OADataType, OAMediaType, OAOperationMethod} from '@e22m4u/js-openapi';
@@ -216,7 +243,7 @@ builder.defineOperation({
 });
 ```
 
-Определение тела ответа для операции.
+Определение тела ответа операции.
 
 ```js
 import {OADataType, OAMediaType, OAOperationMethod} from '@e22m4u/js-openapi';
@@ -251,26 +278,24 @@ builder.defineOperation({
 });
 ```
 
-Определение компонента схемы для использования в следующем примере.
+Определение компонента схемы для следующего примера.
 
 ```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,
-      },
+// структура начальных данных пользователя
+builder.defineSchemaComponent('UserInput', {
+  type: OADataType.OBJECT,
+  properties: {
+    email: {
+      type: OADataType.STRING,
+      format: 'email',
+    },
+    password: {
+      type: OADataType.STRING,
     },
-    required: ['email', 'password'],
   },
+  required: ['email', 'password'],
 });
 ```
 
@@ -310,21 +335,21 @@ builder.defineOperation({
 });
 ```
 
-## Группировка маршрутов
+## Группировка операций
 
-Создание области с общим префиксом пути и тегом.
+Создание группы операций с общим префиксом пути и тегом.
 
 ```js
 import {OAOperationMethod} from '@e22m4u/js-openapi';
 
-// создание области /users
-const usersScope = builder.createScope({
+// создание группы /users
+const usersOps = builder.createOperationGroup({
   pathPrefix: '/users',
   tags: ['User'], // опционально
 });
 
-// маршрут GET /users/{id}
-usersScope.defineOperation({
+// операция GET /users/{id}
+usersOps.defineOperation({
   path: '/{id}',
   method: OAOperationMethod.GET,
   operation: {
@@ -337,8 +362,8 @@ usersScope.defineOperation({
   },
 });
 
-// маршрут DELETE /users/{id}
-usersScope.defineOperation({
+// операция DELETE /users/{id}
+usersOps.defineOperation({
   path: '/{id}',
   method: OAOperationMethod.DELETE,
   operation: {
@@ -352,23 +377,23 @@ usersScope.defineOperation({
 });
 ```
 
-Создание вложенных областей для комбинирования маршрутов.
+Создание вложенных групп для комбинирования операций.
 
 ```js
 import {OAOperationMethod} from '@e22m4u/js-openapi';
 
-// область "/api/v1"
-const v1Scope = builder.createScope({
+// группа "/api/v1"
+const v1Ops = builder.createOperationGroup({
   pathPrefix: '/api/v1',
 });
 
-// область "/api/v1/admin"
-const adminScope = v1Scope.createScope({
+// группа "/api/v1/admin"
+const adminOps = v1Ops.createOperationGroup({
   pathPrefix: '/admin',
 });
 
 // DELETE /api/v1/admin/users/{id}
-adminScope.defineOperation({
+adminOps.defineOperation({
   path: '/users/{id}',
   method: OAOperationMethod.DELETE,
   operation: {
@@ -382,121 +407,176 @@ adminScope.defineOperation({
 });
 ```
 
-## Проверка данных
+## Константы
 
-Проверка данных с помощью объекта схемы.
+Operation Method
 
 ```js
-import {OADataType, validateDataWithOpenApiSchema} from '@e22m4u/js-openapi';
-
-const schema = {
-  type: OADataType.OBJECT,
-  properties: {
-    name: {type: OADataType.STRING},
-    age: {type: OADataType.NUMBER},
-  },
+/**
+ * Operation Method.
+ * https://spec.openapis.org/oas/v3.1.2#path-item-object
+ */
+export const OAOperationMethod = {
+  GET: 'get',
+  PUT: 'put',
+  POST: 'post',
+  DELETE: 'delete',
+  OPTIONS: 'options',
+  HEAD: 'head',
+  PATCH: 'patch',
+  TRACE: 'trace',
 };
+```
 
-const data = {
-  name: 'Fedor',
-  age: 'invalid',
-};
+Parameter Location
 
-validateDataWithOpenApiSchema(data, schema);
-// OADataValidationError:
-// Value at "/age" must be Number, but String was given.
+```js
+/**
+ * Parameter Location.
+ * https://spec.openapis.org/oas/v3.1.2#parameter-locations
+ */
+export const OAParameterLocation = {
+  QUERY: 'query',
+  HEADER: 'header',
+  PATH: 'path',
+  COOKIE: 'cookie',
+};
 ```
 
-Отключение выброса ошибки для ручной обработки результата.
+Parameter Style
 
 ```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.',
-// }
+/**
+ * Parameter Style.
+ * https://spec.openapis.org/oas/v3.1.2#style-values
+ */
+export const OAParameterStyle = {
+  MATRIX: 'matrix',
+  LABEL: 'label',
+  FORM: 'form',
+  SIMPLE: 'simple',
+  SPACE_DELIMITED: 'spaceDelimited',
+  PIPE_DELIMITED: 'pipeDelimited',
+  DEEP_OBJECT: 'deepObject',
+};
 ```
 
-Проверка данных с приведением типов.
+Data type
 
 ```js
-import {OADataType, validateDataWithOpenApiSchema} from '@e22m4u/js-openapi';
+/**
+ * Data type.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1
+ */
+export const OADataType = {
+  STRING: 'string',
+  NUMBER: 'number',
+  INTEGER: 'integer',
+  BOOLEAN: 'boolean',
+  OBJECT: 'object',
+  ARRAY: 'array',
+  NULL: 'null',
+};
+```
 
-const schema = {
-  type: OADataType.OBJECT,
-  properties: {
-    phone: {type: OADataType.STRING},
-    quantity: {type: OADataType.INTEGER},
-    featured: {type: OADataType.BOOLEAN},
-  },
+Data format
+
+```js
+/**
+ * Data format.
+ * https://spec.openapis.org/oas/v3.1.2#dataTypeFormat
+ */
+export const OADataFormat = {
+  // number
+  INT32: 'int32',
+  INT64: 'int64',
+  FLOAT: 'float',
+  DOUBLE: 'double',
+  // date and time
+  DATE: 'date',
+  DATE_TIME: 'date-time',
+  TIME: 'time',
+  DURATION: 'duration',
+  // binary
+  BYTE: 'byte',
+  BINARY: 'binary',
+  // identifiers and network
+  EMAIL: 'email',
+  IDN_EMAIL: 'idn-email',
+  UUID: 'uuid',
+  HOSTNAME: 'hostname',
+  IDN_HOSTNAME: 'idn-hostname',
+  IPV4: 'ipv4',
+  IPV6: 'ipv6',
+  URI: 'uri',
+  URI_REFERENCE: 'uri-reference',
+  IRI: 'iri',
+  IRI_REFERENCE: 'iri-reference',
+  // extra
+  PASSWORD: 'password',
+  REGEX: 'regex',
+  JSON_POINTER: 'json-pointer',
+  RELATIVE_JSON_POINTER: 'relative-json-pointer',
 };
+```
 
-const data = {
-  phone: 88005553535, // приводится к строке
-  quantity: '3',      // приводится к целому числу
-  featured: 'true'    // приводится к логическому значению
+Media type
+
+```js
+/**
+ * Media type.
+ * https://spec.openapis.org/oas/v3.1.2#media-types
+ */
+export const OAMediaType = {
+  TEXT_PLAIN: 'text/plain',
+  TEXT_HTML: 'text/html',
+  APPLICATION_XML: 'application/xml',
+  APPLICATION_JSON: 'application/json',
+  MULTIPART_FORM_DATA: 'multipart/form-data',
 };
+```
 
-const result = validateDataWithOpenApiSchema(data, schema, {
-  coerceTypes: true, // <= приведение типов
-});
-console.log(result);
-// {
-//   isValid: true,
-//   value: {
-//     phone: '88005553535',
-//     quantity: 3,
-//     featured: true
-//   }
-// }
+Security Scheme Type
+
+```js
+/**
+ * Security Scheme Type.
+ * https://spec.openapis.org/oas/v3.1.2#security-scheme-object
+ */
+export const OASecuritySchemeType = {
+  API_KEY: 'apiKey',
+  HTTP: 'http',
+  MUTUAL_TLS: 'mutualTLS',
+  OAUTH_2: 'oauth2',
+  OPEN_ID_CONNECT: 'openIdConnect',
+};
 ```
 
-Проверка данных с разбором JSON.
+Api Key Location
 
 ```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},
-  ],
+/**
+ * Api Key Location.
+ * https://spec.openapis.org/oas/v3.1.2#security-scheme-object
+ */
+export const OAApiKeyLocation = {
+  QUERY: 'query',
+  HEADER: 'header',
+  COOKIE: 'cookie',
 };
+```
 
-const data = [
-  '123',       // приводится к целому числу
-  'true',      // приводится к логическому значению
-  '[1, 2, 3]', // приводится к массиву
-  '{"where": {"id": 10}, "include": "user"}', // приводится к объекту
-];
+Access mode
 
-const result = validateDataWithOpenApiSchema(data, schema, {
-  parseJson: true, // <= разбор JSON
-});
-console.log(result);
-// {
-//   isValid: true,
-//   value: [
-//     123,
-//     true,
-//     [1, 2, 3],
-//     {
-//       where: {
-//         id: 10,
-//       },
-//       include: 'user'
-//     }
-//   ]
-// }
+```js
+/**
+ * Access mode.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#name-readonly-and-writeonly
+ */
+export const OAAccessMode = {
+  READ: 'read',
+  WRITE: 'write',
+};
 ```
 
 ## Тесты