Files
mtusi2026lab4/contracts/extensions.openapi.json
T

586 lines
19 KiB
JSON
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.
{
"openapi": "3.1.0",
"info": {
"title": "MTUSI Messenger — расширение lab4: прямая загрузка",
"version": "1.4.0-ext.1",
"description": "Трек 1. Не меняет обязательный контракт openapi.json: POST /api/v1/chats/{chat_id}/attachments остаётся основным путём. Клиент получает presigned PUT URL и отправляет байты прямо в приватный bucket MinIO, минуя API. Подписаны заголовки content-type, content-length и x-amz-checksum-sha256: хранилище само отвергает тело с другим размером (403 SignatureDoesNotMatch) или другим SHA-256 (400 XAmzContentChecksumMismatch), объект при этом не создаётся. TTL URL — DIRECT_UPLOAD_URL_TTL_SECONDS (300 с по умолчанию). Ключ объекта attachments/<attachment_id>/original раскрывает только UUID вложения; bucket приватный, анонимный доступ запрещён. Незавершённые заявки и объекты убирает уборщик через ATTACHMENT_SWEEP_GRACE_SECONDS после истечения. Вложение видно участникам чата только после успешного complete (status=ready)."
},
"servers": [
{
"url": "http://localhost:8080",
"description": "Локальный учебный стенд"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/api/v1/chats/{chat_id}/attachments/direct-uploads": {
"post": {
"operationId": "initDirectUpload",
"summary": "Заявка на прямую загрузку: вернуть presigned PUT URL",
"parameters": [
{
"name": "chat_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDirectUpload"
}
}
}
},
"responses": {
"201": {
"description": "Заявка создана; вложение pending и не видно никому, кроме загрузки",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectUpload"
}
}
}
},
"400": {
"description": "Некорректное тело, filename или sha256",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Нет или неверен токен",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Чат недоступен",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"413": {
"description": "size_bytes больше 10 MiB",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"415": {
"description": "content_type не image/png и не image/jpeg",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Слишком много незавершённых прямых загрузок пользователя; Retry-After — секунды до освобождения слота (TTL URL).",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
},
"Retry-After": {
"description": "Секунды до повтора.",
"schema": {
"type": "integer",
"minimum": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Зависимость недоступна",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/attachments/{attachment_id}/complete": {
"post": {
"operationId": "completeDirectUpload",
"summary": "Подтвердить прямую загрузку: HEAD объекта и проверка заголовка изображения",
"description": "Только владелец заявки. Проверяет размер и подписанный SHA-256 объекта (HEAD), читает заголовок изображения (до 1 MiB) и сверяет тип и число пикселей. При несоответствии заявка и объект удаляются, повторный complete даёт 404. Повторный complete готового вложения идемпотентен и возвращает 200.",
"parameters": [
{
"name": "attachment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Вложение готово; тело идентично Attachment из openapi.json",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Attachment"
}
}
}
},
"400": {
"description": "Некорректный attachment_id",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Нет или неверен токен",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Заявка не найдена, не принадлежит пользователю или уже удалена",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Объект не получен или не совпадает с заявленным размером/SHA-256",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Слишком много пикселей",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Содержимое не PNG/JPEG или не совпадает с content_type",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Хранилище недоступно",
"headers": {
"X-Request-Id": {
"description": "Идентификатор запроса.",
"schema": {
"type": "string",
"minLength": 1
}
},
"X-Instance-Id": {
"description": "Идентификатор реплики.",
"schema": {
"type": "string",
"minLength": 1
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "openapi.json#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "opaque session token"
}
},
"schemas": {
"CreateDirectUpload": {
"type": "object",
"additionalProperties": false,
"required": [
"filename",
"content_type",
"size_bytes",
"sha256"
],
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"content_type": {
"type": "string",
"enum": [
"image/png",
"image/jpeg"
]
},
"size_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 10485760
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
},
"DirectUpload": {
"type": "object",
"additionalProperties": false,
"required": [
"attachment_id",
"method",
"url",
"headers",
"expires_at"
],
"properties": {
"attachment_id": {
"type": "string",
"format": "uuid"
},
"method": {
"type": "string",
"enum": [
"PUT"
]
},
"url": {
"type": "string",
"format": "uri",
"description": "Presigned URL; содержит подпись, не логировать."
},
"headers": {
"type": "object",
"description": "Заголовки, которые клиент обязан отправить как есть. Content-Length клиент ставит сам; тело должно быть ровно size_bytes.",
"properties": {
"Content-Type": {
"type": "string"
},
"x-amz-checksum-sha256": {
"type": "string"
}
},
"required": [
"Content-Type",
"x-amz-checksum-sha256"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}