Из модели БД в API: DBML в OpenAPI и JSON Schema

Когда модель БД уже спроектирована, схемы ресурсов API во многом её повторяют. Их черновик можно получить автоматически и сосредоточиться на дизайне API, а не на переписывании полей.

Как преобразовать

1. Откройте модель в редакторе DBML.
2. Выберите Файл → Преобразовать в → OpenAPI — схемы данных (или JSON Schema — структуры таблиц).
3. Сохраните результат в проект и доработайте в редакторе OpenAPI или JSON Schema.

Как переводятся типы

SQL	JSON Schema / OpenAPI
int, bigint, serial	integer
numeric, decimal, float, money	number
varchar(n), text	string, maxLength: n
boolean	boolean
date / timestamp, timestamptz	string, format: date / date-time
uuid	string, format: uuid
json, jsonb	без ограничения типа
тип[]	array

• Колонки not null и первичный ключ — в required; остальные допускают null (nullable в OpenAPI 3.0, тип с null в JSON Schema).
• Автоинкрементный ключ — readOnly: в запросах на создание его не передают.
• Перечисления — отдельные схемы с enum.
• Внешний ключ и значение по умолчанию — в description поля («→ users.id»).

Что сделать после

API — не копия таблиц: уберите служебные поля, объедините связанные сущности во вложенные объекты, разделите схемы на запрос и ответ, добавьте пути. Черновик избавляет только от механической части. О подходах к проектированию контрактов — в статье «Contract-first и code-first».

Пример

Table orders {
  id int [pk, increment]
  number varchar(20) [not null, unique]
  user_id int [ref: > users.id]
  created_at timestamptz [not null, default: `now()`]
}

превращается в схему:

orders:
  type: object
  required: [id, number, created_at]
  properties:
    id: {type: integer, readOnly: true}
    number: {type: string, maxLength: 20}
    user_id: {type: integer, nullable: true, description: "→ users.id"}
    created_at: {type: string, format: date-time, description: "default: `now()`"}

Вопросы и ответы

Будут ли пути (paths) для CRUD? Нет, создаются только схемы: какие операции открывать в API — решение дизайна, а не следствие модели.

JSON Schema или OpenAPI — что выбрать? OpenAPI — если дальше проектируете REST API; JSON Schema — если схемы нужны для валидации данных, событий или конфигураций.