@kollors/deep-json-server 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 [English](README.md) | [Русский](README.ru.md)
 
+[GitHub](https://github.com/kollors/deep-json-server) | [npm](https://www.npmjs.com/package/@kollors/deep-json-server)
+
 A small JSON REST mock server with CRUD, pagination, deep filters and recursive relationship embedding. It keeps the database in one readable JSON file and infers soft relations from conventional keys such as `countryId`, `genreIds` and `publisherIds`.
 
 ## Installation
@@ -15,7 +17,8 @@ Add a script to `package.json`:
 ```json
 {
   "scripts": {
-    "mock": "deep-json-server mock/database.json --port 4001"
+    "mock": "deep-json-server mock/database.json --port 4001",
+    "openapi": "deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml"
   }
 }
 ```
@@ -28,6 +31,37 @@ npm run mock
 
 The default address is `http://127.0.0.1:4001`. You can also pass `--host` and `--port`, or set the `HOST` and `PORT` environment variables.
 
+## OpenAPI generation
+
+Create a small configuration file next to the database, for example `mock/database-schema.json`:
+
+```json
+{
+  "movies": {
+    "optional": ["description"],
+    "formats": {
+      "coverSrc": "uri"
+    }
+  },
+  "users": {
+    "formats": {
+      "avatarSrc": "uri",
+      "bornAt": "date"
+    }
+  }
+}
+```
+
+Generate an OpenAPI 3.0.3 file and exit:
+
+```bash
+deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml
+```
+
+The generator infers resources and field types from all database records. Fields present in every record are required unless listed in `optional`; `formats` adds OpenAPI formats such as `date` and `uri`. Nested fields use dot paths, for example `actors.id`.
+
+The generated document describes CRUD endpoints, pagination, sorting, deep filters, `_embed`, and response relations inferred from `...Id` and `...Ids` fields. It can be used as input for tools such as RTK Query OpenAPI Codegen. OpenAPI is generated only when `--generate` is passed; normal server startup does not rewrite the file.
+
 ## Example database
 
 This example is based on a movie catalog. It intentionally has no clothes resource. The genre names are real film genres, while `Gangster film` demonstrates a self-referencing subgenre.
@@ -195,7 +229,7 @@ They are soft references: the server resolves them when requested but does not e
 ## Programmatic API
 
 ```js
-import { createServer, startServer } from '@kollors/deep-json-server';
+import { createServer, generateOpenApi, startServer } from '@kollors/deep-json-server';
 
 const server = await createServer({ databasePath: 'mock/database.json', logger: false });
 
@@ -204,6 +238,8 @@ const response = await server.inject({ method: 'GET', url: '/movies' });
 await server.close();
 
 await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
+
+await generateOpenApi({ databasePath: 'mock/database.json', schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
 ```
 
 `createServer()` is useful for tests because it returns a Fastify instance without opening a network port.

package/README.ru.md

@@ -2,6 +2,8 @@
 
 [Русский](README.ru.md) | [English](README.md)
 
+[GitHub](https://github.com/kollors/deep-json-server) | [npm](https://www.npmjs.com/package/@kollors/deep-json-server)
+
 Небольшой JSON REST mock-сервер с CRUD, пагинацией, глубокой фильтрацией и рекурсивной загрузкой связей. База данных хранится в одном читаемом JSON-файле, а мягкие связи определяются по соглашениям о нейминге ключей: `countryId`, `genreIds`, `publisherIds` и так далее.
 
 ## Установка
@@ -15,7 +17,8 @@ npm install --save-dev @kollors/deep-json-server
 ```json
 {
   "scripts": {
-    "mock": "deep-json-server mock/database.json --port 4001"
+    "mock": "deep-json-server mock/database.json --port 4001",
+    "openapi": "deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml"
   }
 }
 ```
@@ -28,6 +31,37 @@ npm run mock
 
 По умолчанию сервер доступен по адресу `http://127.0.0.1:4001`. Адрес и порт можно задать через `--host` и `--port` либо переменные окружения `HOST` и `PORT`.
 
+## Генерация OpenAPI
+
+Создайте рядом с базой небольшой файл конфигурации, например `mock/database-schema.json`:
+
+```json
+{
+  "movies": {
+    "optional": ["description"],
+    "formats": {
+      "coverSrc": "uri"
+    }
+  },
+  "users": {
+    "formats": {
+      "avatarSrc": "uri",
+      "bornAt": "date"
+    }
+  }
+}
+```
+
+Сгенерируйте OpenAPI 3.0.3 и завершите работу:
+
+```bash
+deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml
+```
+
+Генератор определяет ресурсы и типы полей по всем записям базы. Поля, присутствующие в каждой записи, считаются обязательными, если они не перечислены в `optional`; `formats` добавляет форматы OpenAPI, например `date` и `uri`. Для вложенных полей используются пути через точку, например `actors.id`.
+
+В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed` и связи в ответах, определённые по полям `...Id` и `...Ids`. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--generate`; обычный запуск сервера файл не перезаписывает.
+
 ## Пример базы данных
 
 Пример основан на каталоге фильмов. В нём намеренно нет сущности одежды. Используются реальные жанры фильмов, а `Гангстерский фильм` демонстрирует связь с родительским жанром.
@@ -195,7 +229,7 @@ GET /countries/1?_embed=users
 ## Программный API
 
 ```js
-import { createServer, startServer } from '@kollors/deep-json-server';
+import { createServer, generateOpenApi, startServer } from '@kollors/deep-json-server';
 
 const server = await createServer({ databasePath: 'mock/database.json', logger: false });
 
@@ -204,6 +238,8 @@ const response = await server.inject({ method: 'GET', url: '/movies' });
 await server.close();
 
 await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
+
+await generateOpenApi({ databasePath: 'mock/database.json', schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
 ```
 
 `createServer()` удобен для тестов: он возвращает экземпляр Fastify, не открывая сетевой порт.