init
This commit is contained in:
431
backend/docs/swagger.yaml
Normal file
431
backend/docs/swagger.yaml
Normal file
@@ -0,0 +1,431 @@
|
||||
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
|
||||
Reference in New Issue
Block a user