feat(openapi): OpenAPI 3.1 спецификация REST API#57
Merged
Conversation
Serve an OpenAPI 3.1 document at GET /openapi.json (public), built from a compact route manifest. Request bodies are derived from the actual zod validators via z.toJSONSchema (zod v4) — so the spec can't drift from what the API validates. No new dependency. - lib/openapi: route manifest + buildOpenApiDocument (tags, ApiKeyAuth + SessionCookie security schemes; admin endpoints accept either) - routes/openapi: GET /openapi.json (unauthenticated), built once at start - bin/emit-openapi + `pnpm openapi:emit [file]` for CI / client generation - UI: "API spec ↗" link in the sidebar (same-origin, CSP-safe) + i18n - tests: unit (valid 3.1 doc, security, send body from validator, core paths) + integration (served publicly) Covers the public sending API (/send, /jobs) precisely plus the primary admin resources. Clients/docs are generated from the served spec with standard tooling (openapi-generator, redoc, …). Closes #22 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Что это
OpenAPI 3.1 спецификация REST API (закрывает #22). Отдаётся на
GET /openapi.json(публично), собирается из компактного манифеста роутов. Тела запросов выводятся из реальных zod-валидаторов черезz.toJSONSchema(zod v4) — поэтому спека не может разойтись с тем, что API валидирует. Без новых зависимостей.Surfaces: REST API + dashboard + MCP (генерация клиентов/доков — стандартным тулингом из спеки).
Как работает
lib/openapi: манифест роутов +buildOpenApiDocument(теги, security-схемыApiKeyAuth(X-Api-Key) иSessionCookie; admin-эндпоинты принимают любой из двух).GET /openapi.json(без аутентификации), документ строится один раз при старте.pnpm openapi:emit [file]— выгрузка спеки в файл для CI и генерации клиентов (openapi-generator,redoc, …).Покрытие
Публичный sending API (
/send,/jobs) — точно, с телом запроса изsendBodySchema; плюс основные admin-ресурсы (domains, mailboxes, aliases, suppressions, bounces, api-keys, import, access-rules, fetchmail, migrations, smtp-accounts, webhooks, observability). 29 путей, 16 тегов.Изменения
lib/openapi.ts,routes/openapi.ts,bin/emit-openapi.ts+ скриптopenapi:emit./sendиз валидатора, ключевые пути) + интеграционный (отдаётся публично).Проверки
typecheck·lint·format:check·vitest(525 ✓) ·ui typecheck/build— всё зелёное.pnpm openapi:emitдаёт валидный JSON (29 путей).Заметка
Тела запросов точные (из валидаторов); ответы описаны на высоком уровне (статус + описание) — этого достаточно для генерации клиентов и навигации.
.refine()/.transform()в валидаторах не выразимы в JSON Schema и эмитятся как{}(опцияunrepresentable: 'any'). Встроенный рендер Swagger UI не добавлял намеренно — строгий CSP дашборда блокирует CDN-скрипты; спека отдаётся как JSON, доки генерятся внешним тулингом.Closes #22
🤖 Generated with Claude Code