Add api key for use rest api

2026-06-30 23:32:57 +07:00
parent 2330f279aa
commit be63fc3c10
3 changed files with 2178 additions and 59 deletions
@@ -0,0 +1,350 @@
+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: []