645 lines
16 KiB
YAML
645 lines
16 KiB
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/users:
|
|
get:
|
|
tags:
|
|
- Social Rating
|
|
summary: List users with current social rating
|
|
operationId: listUsersWithRatings
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- in: query
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
default: 50
|
|
responses:
|
|
'200':
|
|
description: Users with current rating values
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UsersResponse'
|
|
'401':
|
|
description: Missing or invalid token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/users/{userId}:
|
|
get:
|
|
tags:
|
|
- Social Rating
|
|
summary: Get user with current social rating
|
|
operationId: getUserWithRating
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: userId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: uint64
|
|
responses:
|
|
'200':
|
|
description: User with current rating value
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserRatingResponse'
|
|
'400':
|
|
description: Invalid user id
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'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/users/{userId}/social-rating/history:
|
|
get:
|
|
tags:
|
|
- Social Rating
|
|
summary: Get social rating history for user
|
|
operationId: getUserRatingHistory
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: userId
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: uint64
|
|
- in: query
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
default: 50
|
|
responses:
|
|
'200':
|
|
description: Rating history for user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryResponse'
|
|
'400':
|
|
description: Invalid user id
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'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/social-rating/operations:
|
|
get:
|
|
tags:
|
|
- Social Rating
|
|
summary: Get recent social rating operations
|
|
operationId: getRecentSocialRatingOperations
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- in: query
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
default: 50
|
|
responses:
|
|
'200':
|
|
description: Recent rating operations across all users
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryResponse'
|
|
'401':
|
|
description: Missing or invalid token
|
|
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
|
|
|
|
UsersResponse:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/UserWithRating'
|
|
required:
|
|
- users
|
|
|
|
UserRatingResponse:
|
|
type: object
|
|
properties:
|
|
user:
|
|
$ref: '#/components/schemas/UserWithRating'
|
|
required:
|
|
- user
|
|
|
|
HistoryResponse:
|
|
type: object
|
|
properties:
|
|
operations:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SocialRatingOperation'
|
|
required:
|
|
- operations
|
|
|
|
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
|
|
|
|
UserWithRating:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: uint64
|
|
example: 2
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: user@example.com
|
|
isAdmin:
|
|
type: boolean
|
|
example: false
|
|
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:
|
|
- id
|
|
- email
|
|
- isAdmin
|
|
- score
|
|
- 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
|