Files
mtusi2026lab3/src/docs/examples.ts
T
2026-11-01 14:11:53 +03:00

344 lines
10 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
const ALICE_ID = '11111111-1111-4111-8111-111111111111';
const BOB_ID = '22222222-2222-4222-8222-222222222222';
const CHAT_ID = '33333333-3333-4333-8333-333333333333';
const MESSAGE_ID = '44444444-4444-4444-8444-444444444444';
const CURSOR =
'eyJjaGF0SWQiOiIzMzMzMzMzMy0zMzMzLTQzMzMtODMzMy0zMzMzMzMzMzMzMzMiLCJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC04NDQ0LTQ0NDQ0NDQ0NDQ0NCJ9';
const ALICE = {
id: ALICE_ID,
username: 'alice',
display_name: 'Алиса',
created_at: '2026-09-01T12:00:00.000Z',
};
const CHAT = {
id: CHAT_ID,
title: 'Проект по ВНП',
member_ids: [ALICE_ID, BOB_ID],
created_at: '2026-09-01T12:01:00.000Z',
};
const MESSAGE = {
id: MESSAGE_ID,
chat_id: CHAT_ID,
sender_id: ALICE_ID,
text: 'Привет, Боб! 👋',
created_at: '2026-09-01T12:02:00.000Z',
};
export interface Example {
summary: string;
value: unknown;
}
export interface OperationExamples {
request?: Record<string, Example>;
responses: Record<string, Record<string, Example>>;
}
function example(summary: string, value: unknown): Example {
return { summary, value };
}
function error(code: string, message: string): unknown {
return {
error: {
code,
message,
request_id: '9b2c6f1e-5d4a-4c3b-8a2f-1e0d9c8b7a6f',
},
};
}
const UNAUTHORIZED = {
missing: example(
'Нет/неверный/истёкший/отозванный Bearer-токен',
error('unauthorized', 'missing or invalid session'),
),
};
const UNAVAILABLE = {
database: example(
'PostgreSQL недоступен',
error('unavailable', 'database unavailable'),
),
};
const CHAT_NOT_FOUND = {
notFound: example(
'Чата нет или вызывающий не участник (не 403)',
error('not_found', 'chat not found'),
),
};
const INVALID_CHAT_ID = example(
'chat_id не UUID',
error('invalid_request', 'chatId must be a valid UUID'),
);
export const GUIDE = `
Учебный мессенджер, лабораторная 3: PostgreSQL, сессии, Redis-кэш сессий.
Документ — обязательный контракт \`contracts/openapi.json\`, дополненный примерами запросов и ответов.
**Как пройти сценарий в Swagger UI**
1. \`POST /api/v1/users\` — зарегистрируйте пользователей (примеры alice, bob, eve в списке Examples). Повторная регистрация того же username — 409, меняйте username.
2. **Authorize → basicAuth**: username и password из шага 1 → \`POST /api/v1/auth/sessions\` → скопируйте \`token\`.
3. **Authorize → bearerAuth**: вставьте token (без слова Bearer). Basic отправляется только на вход, остальные запросы идут с Bearer.
4. \`GET /api/v1/users/me\` — свой id; id второго участника — из ответа его регистрации.
5. \`POST /api/v1/chats\` с \`member_ids\` = [свой id, id собеседника] → \`chat_id\`.
6. \`POST /api/v1/chats/{chat_id}/messages\` с заголовком \`Idempotency-Key\` (любая строка из \`A-Za-z0-9._:-\`, до 128 символов). Повтор с тем же ключом и телом вернёт то же сообщение, с другим телом — 409. Затем \`GET …/messages?limit=1\` и следующая страница с \`cursor\` = \`next_cursor\`.
7. Чтобы действовать от другого пользователя: Logout в Authorize, вход им и новый token.
8. \`DELETE /api/v1/auth/sessions/current\` — logout; тот же token дальше даёт 401.
Сессия живёт \`SESSION_TTL_SECONDS\` (по умолчанию 3600 с). Пароль — 12–128 символов Unicode, двоеточие допустимо.
`;
export const OPERATION_EXAMPLES: Record<string, OperationExamples> = {
'GET /health/live': {
responses: {
'200': { ok: example('Процесс жив', { status: 'ok' }) },
},
},
'GET /health/ready': {
responses: {
'200': {
ok: example('PostgreSQL доступен (Redis не критичен)', {
status: 'ok',
}),
},
'503': UNAVAILABLE,
},
},
'POST /api/v1/users': {
request: {
alice: example('Алиса', {
username: 'alice',
display_name: 'Алиса',
password: 'Alice-password-123',
}),
bob: example('Боб', {
username: 'bob',
display_name: 'Боб',
password: 'Bob-password-123',
}),
eve: example('Ева (посторонняя)', {
username: 'eve',
display_name: 'Ева',
password: 'Eve-password-123',
}),
colon: example('Пароль с двоеточием и эмодзи', {
username: 'carol',
display_name: 'Кэрол 🌸',
password: 'пароль:с:двоеточием🔑',
}),
},
responses: {
'201': { created: example('Пользователь создан', ALICE) },
'400': {
username: example(
'username не соответствует [a-z0-9_]{3,32}',
error('invalid_request', 'username must match [a-z0-9_]{3,32}'),
),
password: example(
'password короче 12 символов',
error(
'invalid_request',
'password must be between 12 and 128 Unicode code points',
),
),
extra: example(
'Лишнее поле в JSON',
error('invalid_request', 'property extra should not exist'),
),
},
'409': {
taken: example(
'username уже занят',
error('conflict', 'username is already taken'),
),
},
'503': UNAVAILABLE,
},
},
'POST /api/v1/auth/sessions': {
responses: {
'201': {
created: example('Сессия создана', {
token: 'q8Hn3vXl0ZbJ7mWcY2sRkT5uPaE9dFgVhN1oLxI4w6A',
token_type: 'Bearer',
expires_at: '2026-09-01T13:00:00.000Z',
user: ALICE,
}),
},
'401': {
invalid: example(
'Неверный пароль, неизвестный пользователь или нет Basic — ответ одинаковый',
error('unauthorized', 'invalid credentials'),
),
},
'503': UNAVAILABLE,
},
},
'DELETE /api/v1/auth/sessions/current': {
responses: {
'401': UNAUTHORIZED,
'503': UNAVAILABLE,
},
},
'GET /api/v1/users/me': {
responses: {
'200': { me: example('Текущий пользователь из сессии', ALICE) },
'401': UNAUTHORIZED,
'503': UNAVAILABLE,
},
},
'POST /api/v1/chats': {
request: {
pair: example('Чат Алисы и Боба', {
title: CHAT.title,
member_ids: CHAT.member_ids,
}),
solo: example('Чат только с собой', {
title: 'Заметки',
member_ids: [ALICE_ID],
}),
},
responses: {
'201': { created: example('Чат создан атомарно', CHAT) },
'400': {
noCaller: example(
'Вызывающий не в member_ids',
error('invalid_request', 'member_ids must include the caller'),
),
unknown: example(
'Неизвестный участник — транзакция откатывается',
error('invalid_request', 'member_ids contain an unknown user'),
),
duplicate: example(
'Дубликаты в member_ids',
error(
'invalid_request',
"All member_ids's elements must be unique",
),
),
},
'401': UNAUTHORIZED,
'503': UNAVAILABLE,
},
},
'GET /api/v1/chats': {
responses: {
'200': {
page: example('Страница чатов с продолжением', {
items: [CHAT],
next_cursor: 'eyJpZCI6IjMzMzMzMzMzLTMzMzMtNDMzMy04MzMzLTMzMzMzMzMzMzMzMyJ9',
}),
last: example('Последняя страница', {
items: [CHAT],
next_cursor: null,
}),
},
'400': {
limit: example(
'limit вне 1–100',
error('invalid_request', 'limit must be between 1 and 100'),
),
cursor: example(
'Испорченный или чужой cursor',
error('invalid_request', 'invalid cursor'),
),
},
'401': UNAUTHORIZED,
'503': UNAVAILABLE,
},
},
'GET /api/v1/chats/{chat_id}': {
responses: {
'200': { chat: example('Чат, где вызывающий — участник', CHAT) },
'400': { chatId: INVALID_CHAT_ID },
'401': UNAUTHORIZED,
'404': CHAT_NOT_FOUND,
'503': UNAVAILABLE,
},
},
'POST /api/v1/chats/{chat_id}/messages': {
request: {
text: example('Обычное сообщение', { text: MESSAGE.text }),
long: example('Максимум — 4000 символов Unicode', {
text: 'Длинный текст…',
}),
},
responses: {
'201': {
created: example('Отправитель берётся из сессии', MESSAGE),
},
'400': {
blank: example(
'Пустой или пробельный текст',
error(
'invalid_request',
'text must not be empty or whitespace-only',
),
),
sender: example(
'sender_id в теле не принимается',
error('invalid_request', 'property sender_id should not exist'),
),
chatId: INVALID_CHAT_ID,
key: example(
'Нет Idempotency-Key или неверный формат',
error(
'invalid_request',
'Idempotency-Key header must match [A-Za-z0-9._:-]{1,128}',
),
),
},
'401': UNAUTHORIZED,
'404': CHAT_NOT_FOUND,
'409': {
keyReused: example(
'Тот же Idempotency-Key с другим телом',
error(
'conflict',
'Idempotency-Key was already used with a different request',
),
),
},
'503': UNAVAILABLE,
},
},
'GET /api/v1/chats/{chat_id}/messages': {
responses: {
'200': {
page: example('Страница истории (limit=1) с cursor', {
items: [MESSAGE],
next_cursor: CURSOR,
}),
last: example('Последняя страница', {
items: [MESSAGE],
next_cursor: null,
}),
},
'400': {
otherChat: example(
'cursor от другого чата',
error('invalid_request', 'cursor belongs to a different chat'),
),
cursor: example(
'Испорченный cursor или cursor несуществующего сообщения',
error('invalid_request', 'invalid cursor'),
),
limit: example(
'limit вне 1–100',
error('invalid_request', 'limit must be between 1 and 100'),
),
},
'401': UNAUTHORIZED,
'404': CHAT_NOT_FOUND,
'503': UNAVAILABLE,
},
},
};