openapi: 3.0.3
info:
  title: NoCopy API - API Keys Management
  description: |
    API для управления пользовательскими API ключами.
    Включает контроллер: ApiKeyController
    Позволяет создавать, просматривать и отзывать 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: []