350 lines
13 KiB
YAML
350 lines
13 KiB
YAML
|
openapi: 3.0.3
|
||
|
|
info:
|
||
|
|
title: NoCopy API - API Keys
|
||
|
|
description: API для управления пользовательскими API ключами
|
||
|
|
version: 1.0.0
|
||
|
|
contact:
|
||
|
|
name: NoCopy
|
||
|
|
|
||
|
|
servers:
|
||
|
|
- url: http://localhost:8080
|
||
|
|
description: Локальный
|
||
|
|
- url: https://dev-workspace.not-copy.com/
|
||
|
|
description: Дев
|
||
|
|
|
||
|
|
tags:
|
||
|
|
- name: User
|
||
|
|
description: Управление пользовательскими данными и API ключами
|
||
|
|
|
||
|
|
paths:
|
||
|
|
/api/user/api-keys:
|
||
|
|
post:
|
||
|
|
tags:
|
||
|
|
- User
|
||
|
|
summary: Создание API ключа
|
||
|
|
description: |
|
||
|
|
Создаёт новый API ключ для пользователя.
|
||
|
|
- Требуется авторизация (Bearer токен)
|
||
|
|
- Если имя не указано, будет присвоено "Unnamed key"
|
||
|
|
- Возвращает полный ключ только один раз при создании
|
||
|
|
- Префикс ключа можно использовать для идентификации без раскрытия секрета
|
||
|
|
operationId: createApiKey
|
||
|
|
security:
|
||
|
|
- BearerAuth: []
|
||
|
|
requestBody:
|
||
|
|
required: true
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
name:
|
||
|
|
type: string
|
||
|
|
description: Название ключа для идентификации (опционально)
|
||
|
|
example: "My API Key"
|
||
|
|
maxLength: 255
|
||
|
|
examples:
|
||
|
|
withName:
|
||
|
|
summary: С указанием названия
|
||
|
|
value:
|
||
|
|
name: "Production Key"
|
||
|
|
withDescription:
|
||
|
|
summary: С описательным названием
|
||
|
|
value:
|
||
|
|
name: "Key for mobile app"
|
||
|
|
withoutName:
|
||
|
|
summary: Без названия (по умолчанию "Unnamed key")
|
||
|
|
value: {}
|
||
|
|
minimalExample:
|
||
|
|
summary: Пустое тело запроса
|
||
|
|
value: {}
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: Ключ успешно создан
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
summary: API ключ создан
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: "API key created successfully"
|
||
|
|
message_body:
|
||
|
|
apiKey: "sk-live-abc123def456789ghi012jkl345mno678"
|
||
|
|
successWithDescription:
|
||
|
|
summary: API ключ с описанием создан
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: "API key created successfully"
|
||
|
|
message_body:
|
||
|
|
apiKey: "sk-test-xyz987abc654def321ghi098jkl765mno"
|
||
|
|
'401':
|
||
|
|
description: Неавторизованный доступ
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
unauthorized:
|
||
|
|
summary: Токен не предоставлен или недействителен
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 7
|
||
|
|
message_desc: "Authentication required"
|
||
|
|
message_body: null
|
||
|
|
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- User
|
||
|
|
summary: Получение списка API ключей
|
||
|
|
description: |
|
||
|
|
Возвращает все API ключи текущего пользователя.
|
||
|
|
|
||
|
|
**Особенности:**
|
||
|
|
- Требуется авторизация (Bearer токен)
|
||
|
|
- Полные ключи не возвращаются, только префиксы
|
||
|
|
- Включает информацию об активности и времени использования
|
||
|
|
operationId: listApiKeys
|
||
|
|
security:
|
||
|
|
- BearerAuth: []
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: Список ключей пользователя
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
summary: Список с несколькими ключами
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: null
|
||
|
|
message_body:
|
||
|
|
- id: 1
|
||
|
|
name: "Production Key"
|
||
|
|
prefix: "sk-live-abc123..."
|
||
|
|
isActive: true
|
||
|
|
createdAt: "2025-01-15T10:30:00Z"
|
||
|
|
lastUsedAt: "2025-06-30T14:22:00Z"
|
||
|
|
- id: 2
|
||
|
|
name: "Key for mobile app"
|
||
|
|
prefix: "sk-live-def456..."
|
||
|
|
isActive: true
|
||
|
|
createdAt: "2025-03-20T08:00:00Z"
|
||
|
|
lastUsedAt: "2025-06-29T18:45:00Z"
|
||
|
|
- id: 3
|
||
|
|
name: "Old Development Key"
|
||
|
|
prefix: "sk-test-ghi789..."
|
||
|
|
isActive: false
|
||
|
|
createdAt: "2025-02-10T12:00:00Z"
|
||
|
|
lastUsedAt: "2025-05-15T09:30:00Z"
|
||
|
|
singleKey:
|
||
|
|
summary: Один активный ключ
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: null
|
||
|
|
message_body:
|
||
|
|
- id: 1
|
||
|
|
name: "My API Key"
|
||
|
|
prefix: "sk-live-abc123..."
|
||
|
|
isActive: true
|
||
|
|
createdAt: "2025-06-01T00:00:00Z"
|
||
|
|
lastUsedAt: null
|
||
|
|
empty:
|
||
|
|
summary: Нет созданных ключей
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: null
|
||
|
|
message_body: []
|
||
|
|
'401':
|
||
|
|
description: Неавторизованный доступ
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
unauthorized:
|
||
|
|
summary: Токен не предоставлен или недействителен
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 7
|
||
|
|
message_desc: "Authentication required"
|
||
|
|
message_body: null
|
||
|
|
|
||
|
|
/api/user/api-keys/{keyId}:
|
||
|
|
delete:
|
||
|
|
tags:
|
||
|
|
- User
|
||
|
|
summary: Отзыв (удаление) API ключа
|
||
|
|
description: |
|
||
|
|
Деактивирует API ключ пользователя. Ключ становится неактивным и больше не может использоваться.
|
||
|
|
|
||
|
|
**Особенности:**
|
||
|
|
- Требуется авторизация (Bearer токен)
|
||
|
|
- Пользователь может отозвать только свои ключи
|
||
|
|
- Отозванный ключ нельзя восстановить (нужно создавать новый)
|
||
|
|
operationId: revokeApiKey
|
||
|
|
security:
|
||
|
|
- BearerAuth: []
|
||
|
|
parameters:
|
||
|
|
- name: keyId
|
||
|
|
in: path
|
||
|
|
required: true
|
||
|
|
schema:
|
||
|
|
type: integer
|
||
|
|
format: int64
|
||
|
|
description: ID ключа для отзыва
|
||
|
|
example: 1
|
||
|
|
responses:
|
||
|
|
'200':
|
||
|
|
description: Ключ успешно отозван
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
summary: Ключ отозван
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 0
|
||
|
|
message_desc: null
|
||
|
|
message_body: null
|
||
|
|
'401':
|
||
|
|
description: Неавторизованный доступ
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
unauthorized:
|
||
|
|
summary: Токен не предоставлен или недействителен
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 7
|
||
|
|
message_desc: "Authentication required"
|
||
|
|
message_body: null
|
||
|
|
'403':
|
||
|
|
description: Доступ запрещён (ключ не принадлежит пользователю)
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
forbidden:
|
||
|
|
summary: Ключ принадлежит другому пользователю
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 6
|
||
|
|
message_desc: "Access denied"
|
||
|
|
message_body: null
|
||
|
|
'404':
|
||
|
|
description: Ключ не найден
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: '#/components/schemas/BaseResponse'
|
||
|
|
examples:
|
||
|
|
notFound:
|
||
|
|
summary: Ключ с указанным ID не существует
|
||
|
|
value:
|
||
|
|
msg_id: null
|
||
|
|
message_code: 4
|
||
|
|
message_desc: "API key not found"
|
||
|
|
message_body:
|
||
|
|
keyId: 999
|
||
|
|
|
||
|
|
components:
|
||
|
|
schemas:
|
||
|
|
BaseResponse:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
msg_id:
|
||
|
|
type: integer
|
||
|
|
description: Идентификатор сообщения (может быть null)
|
||
|
|
nullable: true
|
||
|
|
example: null
|
||
|
|
message_code:
|
||
|
|
type: integer
|
||
|
|
description: |
|
||
|
|
Код результата:
|
||
|
|
- 0 - Успешно
|
||
|
|
- 4 - Ресурс не найден
|
||
|
|
- 6 - Доступ запрещён
|
||
|
|
- 7 - Требуется авторизация
|
||
|
|
example: 0
|
||
|
|
message_desc:
|
||
|
|
type: string
|
||
|
|
description: Описание результата операции (может быть null)
|
||
|
|
nullable: true
|
||
|
|
example: "API key created successfully"
|
||
|
|
message_body:
|
||
|
|
description: Данные ответа
|
||
|
|
nullable: true
|
||
|
|
oneOf:
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
apiKey:
|
||
|
|
type: string
|
||
|
|
description: Полный API ключ (только при создании)
|
||
|
|
example: "sk-live-abc123def456..."
|
||
|
|
description: Ответ при создании ключа
|
||
|
|
- type: array
|
||
|
|
items:
|
||
|
|
$ref: '#/components/schemas/ApiKeyInfo'
|
||
|
|
description: Список ключей пользователя
|
||
|
|
- type: object
|
||
|
|
description: Пустой объект или null
|
||
|
|
nullable: true
|
||
|
|
example: null
|
||
|
|
|
||
|
|
ApiKeyInfo:
|
||
|
|
type: object
|
||
|
|
description: Информация об API ключе
|
||
|
|
properties:
|
||
|
|
id:
|
||
|
|
type: integer
|
||
|
|
format: int64
|
||
|
|
description: Уникальный идентификатор ключа
|
||
|
|
example: 1
|
||
|
|
name:
|
||
|
|
type: string
|
||
|
|
description: Название ключа
|
||
|
|
example: "Production Key"
|
||
|
|
prefix:
|
||
|
|
type: string
|
||
|
|
description: Префикс ключа для идентификации
|
||
|
|
example: "sk-live-abc123..."
|
||
|
|
isActive:
|
||
|
|
type: boolean
|
||
|
|
description: Активен ли ключ
|
||
|
|
example: true
|
||
|
|
createdAt:
|
||
|
|
type: string
|
||
|
|
format: date-time
|
||
|
|
description: Дата и время создания ключа
|
||
|
|
example: "2025-01-15T10:30:00Z"
|
||
|
|
lastUsedAt:
|
||
|
|
type: string
|
||
|
|
format: date-time
|
||
|
|
nullable: true
|
||
|
|
description: Дата и время последнего использования (null если не использовался)
|
||
|
|
example: "2025-06-30T14:22:00Z"
|
||
|
|
|
||
|
|
securitySchemes:
|
||
|
|
BearerAuth:
|
||
|
|
type: http
|
||
|
|
scheme: bearer
|
||
|
|
bearerFormat: JWT
|
||
|
|
description: JWT токен для авторизации (получить через /api/auth)
|
||
|
|
|
||
|
|
security:
|
||
|
|
- BearerAuth: []
|