social-rating/backend/docs/swagger.yaml

openapi: 3.0.3
info:
  title: Social Raiting API
  version: 1.0.0
  description: |
    API for authentication, user management, and social rating operations.

    Social rating values are allowed to go below zero. Decrease operations continue
    subtracting from the current score without applying a lower bound.
servers:
  - url: http://localhost:8080
    description: Local backend
tags:
  - name: Health
  - name: Auth
  - name: Social Rating
paths:
  /ping:
    get:
      tags:
        - Health
      summary: Health check
      operationId: ping
      responses:
        '200':
          description: Backend is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'

  /api/auth/login:
    post:
      tags:
        - Auth
      summary: Login user
      operationId: loginUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/me:
    get:
      tags:
        - Auth
      summary: Get current user
      operationId: getCurrentUser
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/register:
    post:
      tags:
        - Auth
      summary: Register user
      description: Only authenticated admin users may create new users.
      operationId: registerUser
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/social-rating/increase:
    post:
      tags:
        - Social Rating
      summary: Increase social rating
      operationId: increaseSocialRating
      description: Adds a positive amount to the target user's current social rating.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeSocialRatingRequest'
      responses:
        '200':
          description: Social rating increased
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeSocialRatingResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Target or actor user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/social-rating/decrease:
    post:
      tags:
        - Social Rating
      summary: Decrease social rating
      operationId: decreaseSocialRating
      description: |
        Subtracts a positive amount from the target user's current social rating.
        The resulting score may be negative.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeSocialRatingRequest'
      responses:
        '200':
          description: Social rating decreased
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeSocialRatingResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Target or actor user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    PingResponse:
      type: object
      properties:
        message:
          type: string
          example: ok
      required:
        - message

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: invalid credentials
      required:
        - error

    LoginRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: admin@example.com
        password:
          type: string
          format: password
          example: strong-password
      required:
        - email
        - password

    RegisterRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          format: password
          minLength: 8
          example: strong-password
        isAdmin:
          type: boolean
          example: false
      required:
        - email
        - password

    ChangeSocialRatingRequest:
      type: object
      properties:
        targetUserId:
          type: integer
          format: uint64
          example: 2
        amount:
          type: integer
          minimum: 1
          default: 1
          example: 3
        reason:
          type: string
          example: helpful review
        source:
          type: string
          example: api
      required:
        - targetUserId

    AuthResponse:
      type: object
      properties:
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        user:
          $ref: '#/components/schemas/User'
      required:
        - token
        - user

    UserResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
      required:
        - user

    User:
      type: object
      properties:
        id:
          type: integer
          format: uint64
          example: 1
        email:
          type: string
          format: email
          example: admin@example.com
        isAdmin:
          type: boolean
          example: true
        socialRating:
          $ref: '#/components/schemas/UserSocialRating'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - isAdmin
        - createdAt
        - updatedAt

    UserSocialRating:
      type: object
      properties:
        userId:
          type: integer
          format: uint64
          example: 2
        score:
          type: integer
          example: -4
        lastOperationId:
          type: integer
          format: uint64
          nullable: true
          example: 15
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - userId
        - score
        - createdAt
        - updatedAt

    SocialRatingOperation:
      type: object
      properties:
        id:
          type: integer
          format: uint64
          example: 15
        targetUserId:
          type: integer
          format: uint64
          example: 2
        actorUserId:
          type: integer
          format: uint64
          nullable: true
          example: 1
        delta:
          type: integer
          example: -3
        operationType:
          type: string
          example: decrease
        reason:
          type: string
          example: spam
        source:
          type: string
          example: api
        balanceAfter:
          type: integer
          example: -4
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - targetUserId
        - delta
        - operationType
        - balanceAfter
        - createdAt

    ChangeSocialRatingResponse:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/SocialRatingOperation'
        currentRating:
          $ref: '#/components/schemas/UserSocialRating'
      required:
        - operation
        - currentRating