Юрий Белк – Full stack Developer (страница 9)
description: OK
content:
application/json:
schema:
$ref: "/components/schemas/VersionResponse"
components:
schemas:
HealthResponse:
type: object
additionalProperties: false
required: [status]
properties:
status:
type: string
enum: [ok]
VersionResponse:
type: object
additionalProperties: false
required: [version]
properties:
version:
type: string
example: "0.1.0"
Почему мы сразу добавили additionalProperties: false
Это важная деталь. Она означает: в ответах не должно быть неожиданных полей.
Если это не включать, сервер может вернуть лишнее, фронт случайно начнёт это использовать, а потом вы захотите убрать поле – и получите «тихий» breaking change.
С additionalProperties: false API становится строже, зато стабильнее.
Договоримся о стиле ошибок (на будущее)
Пока в контракте нет ошибок, но уже сейчас полезно задать единый формат. Тогда все реализации будут возвращать одно и то же.
Добавим схему ошибки в components/schemas (даже если эндпоинты пока её не используют):
yaml
components:
schemas:
ApiError:
type: object
additionalProperties: false
required: [code, message]
properties:
code:
type: string
example: "VALIDATION_ERROR"
message:
type: string
example: "Invalid request"
details:
type: object
additionalProperties: true
description: Дополнительная информация (опционально)
Позже мы начнём ссылаться на ApiError в ответах 400/401/404/500. Сейчас важно: мы заранее закрепили формат.
Генерируем клиентов и типы
OpenAPI полезен сам по себе как документация. Но настоящая сила – в генерации.
Что мы обычно хотим генерировать:
– TypeScript типы для фронтенда и e2e‑тестов;
– TypeScript API клиент (чтобы не писать fetch вручную);
– опционально: клиенты для других языков (если нужно).
Какие инструменты можно использовать
Ниже несколько популярных вариантов. В книге можно выбрать один (или даже сменить позже), главное – чтобы процесс был повторяемым.
– OpenAPI Generator – умеет генерировать почти всё, поддерживает массу языков.
– Swagger Codegen – старый, но встречается.
– Для TS:
– генерация типов отдельно (например, из схем),
– генерация клиента (fetch/axios).
Практический совет: для старта проще всего выбрать один генератор, который делает TS‑клиент и типы, и пользоваться им везде.
Куда складывать результат
Есть два подхода: