mirror of
https://github.com/Govor-team/Govor.git
synced 2026-07-21 19:54:55 +00:00
GitBook: No commit message
This commit is contained in:
stalcke2288969
committed by
gitbook-bot
gitbook-bot
parent
53ea25f9fd
commit
19f1ccdfd5
@@ -0,0 +1,45 @@
|
||||
---
|
||||
description: How to work with jwt tokens
|
||||
icon: user
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
### <mark style="color:$info;">Components</mark>
|
||||
|
||||
* **AuthController**: Handles registration and login.
|
||||
* **Route**: `/api/auth`
|
||||
* **RefreshController**: Manages token refresh.
|
||||
* **Route**: `/api/auth/token`
|
||||
|
||||
### <mark style="color:$info;">Authentication Process</mark>
|
||||
|
||||
* **Registration**:
|
||||
* **Endpoint**: `POST /api/auth/register`
|
||||
* **Input**: `RegistrationRequest` (name, password, inviteLink, deviceInfo)
|
||||
* **Output**: Access token
|
||||
* **Action**: Validates invite, registers user, opens session.
|
||||
* **Login**:
|
||||
* **Endpoint**: `POST /api/auth/login`
|
||||
* **Input**: `LoginRequest` (name, password, deviceInfo)
|
||||
* **Output**: Access token
|
||||
* **Action**: Authenticates user, opens session.
|
||||
* **Token Refresh**:
|
||||
* **Endpoint**: `POST /api/auth/token/refresh`
|
||||
* **Input**: `RefreshTokenRequest` (refreshToken)
|
||||
* **Output**: `RefreshTokenResponse` (accessToken, refreshToken)
|
||||
* **Action**: Refreshes expired access token.
|
||||
|
||||
### <mark style="color:$info;">Token Usage</mark>
|
||||
|
||||
* **Access Token**:
|
||||
* **Request**: Obtain during registration or login.
|
||||
* **Refresh**: Request via `/api/auth/token/refresh` when expired (e.g., 02:12 PM CEST, July 21, 2025).
|
||||
* **Refresh Token**:
|
||||
* **Request**: Received during registration or login.
|
||||
* **Refresh**: Use to obtain new access token when current one expires.
|
||||
|
||||
### Security
|
||||
|
||||
* **Protocol**: Requires HTTPS.
|
||||
* **Storage**: Store refresh token in HTTP-only cookie with `Secure` and `SameSite=Strict`.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
description: >-
|
||||
Controller for handling user authentication operations, including registration
|
||||
and login, with session management and invite-based registration.
|
||||
---
|
||||
|
||||
# AuthController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/auth`
|
||||
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Register</mark>
|
||||
|
||||
* **Description**: Registers a new user using a valid invite link and opens a user session, returning an authentication token.
|
||||
* **Route**: `[POST] api/auth/register`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `RegistrationRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"inviteLink": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful registration and session creation.
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If the user already exists: `"Registration failed: user already exists."`
|
||||
* If the invite link is invalid: `"Invite link invalid."`
|
||||
* If the username is invalid: `"Invalid username: <error_message>"`
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred. Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">Login</mark>
|
||||
|
||||
* **Description**: Authenticates an existing user and opens a session, returning an authentication token.
|
||||
* **Route**: `[POST] api/auth/login`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `LoginRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful login and session creation.
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If the user does not exist: `"Login failed: user does not exist."`
|
||||
* If the username or password is incorrect: `"Login failed: username or password is incorrect."`
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred. Please try again later."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### RegistrationRequest
|
||||
|
||||
* **Description**: Model for registration request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"inviteLink": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### LoginRequest
|
||||
|
||||
* **Description**: Model for login request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"password": "string",
|
||||
"deviceInfo": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### RefreshResult
|
||||
|
||||
* **Description**: Model for refresh token response data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string",
|
||||
"accessToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Not applicable (handled by session service).
|
||||
* **Invalid Operations**: Registration fails if the user already exists, invite link is invalid, or username is invalid, returning `400 Bad Request`.
|
||||
* **Unauthorized Access**: Not applicable (endpoint is `[AllowAnonymous]`).
|
||||
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs successful registration and login events with username and user ID.
|
||||
* Logs session opening events with username and user ID.
|
||||
* Logs warnings for specific exceptions (e.g., user already exists, invalid invite link, login failures).
|
||||
* Logs errors for unexpected exceptions during registration and login.
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
description: >-
|
||||
Controller for managing token refresh operations, allowing users to refresh
|
||||
their access tokens using a valid refresh token.
|
||||
---
|
||||
|
||||
# RefreshController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/auth/token`
|
||||
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Refresh</mark>
|
||||
|
||||
* **Description**: Refreshes an access token using a provided refresh token and returns a new access token and refresh token pair.
|
||||
* **Route**: `[POST] api/auth/token/refresh`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: `RefreshTokenRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a new access token and refresh token upon successful refresh.
|
||||
|
||||
```json
|
||||
{
|
||||
"accessToken": "string",
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
* <mark style="color:$warning;">**400 Bad Request**</mark>: If model validation fails or the refresh token is empty.
|
||||
|
||||
```json
|
||||
"Refresh token cant be empty."
|
||||
```
|
||||
* <mark style="color:$warning;">**401 Unauthorized**</mark>: If the refresh token is invalid or authorization fails.
|
||||
|
||||
```json
|
||||
"Invalid refresh token"
|
||||
```
|
||||
* <mark style="color:$danger;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"An unexpected error occurred."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### RefreshTokenRequest
|
||||
|
||||
* **Description**: Model for refresh token request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### RefreshTokenResponse
|
||||
|
||||
* **Description**: Model for refresh token response data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"accessToken": "string",
|
||||
"refreshToken": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Not applicable (handled by session service).
|
||||
* **Invalid Operations**: Returns `400 Bad Request` if the refresh token is empty or invalid.
|
||||
* **Unauthorized Access**: Returns `401 Unauthorized` if the refresh token fails authorization.
|
||||
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for invalid or failed refresh token attempts.
|
||||
* Logs errors for unexpected exceptions during token refresh.
|
||||
@@ -0,0 +1,259 @@
|
||||
---
|
||||
description: Controller for loading chat messages for users and groups with pagination.
|
||||
---
|
||||
|
||||
# ChatLoadController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/chats`
|
||||
* **Authorize**: Requires authenticated user with roles "Admin" or "User" (`[Authorize(Roles = "Admin, User")]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">GetGroupMessages</mark>
|
||||
|
||||
* **Description**: Retrieves messages from a specified group chat with pagination.
|
||||
* **Route**: `[GET] api/chats/group-messages`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `chatId` (Guid, required): ID of the group chat.
|
||||
* **Query Parameter**: `query` (`MessageQuery`, required) with:
|
||||
* `startMessageId` (Guid?, optional): ID of the starting message.
|
||||
* `before` (int, default=20): Number of messages before the start.
|
||||
* `after` (int, default=2): Number of messages after the start.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of group chat messages.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If `before` or `after` is negative or total exceeds 100: `"Values must be non-negative and total must not exceed 100."`
|
||||
* If an argument or resource is invalid: `"string"`
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetUserMessages</mark>
|
||||
|
||||
* **Description**: Retrieves messages from a specified user chat with pagination.
|
||||
* **Route**: `[GET] api/chats/user-messages`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `userId` (Guid, required): ID of the target user.
|
||||
* **Query Parameter**: `query` (`MessageQuery`, required) with:
|
||||
* `startMessageId` (Guid?, optional): ID of the starting message.
|
||||
* `before` (int, default=20): Number of messages before the start.
|
||||
* `after` (int, default=2): Number of messages after the start.
|
||||
* **Responses**:
|
||||
* **200 OK**: Returns a list of user chat messages.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
* **400 Bad Request**:
|
||||
* If `before` or `after` is negative or total exceeds 100: `"Values must be non-negative and total must not exceed 100."`
|
||||
* If an operation or resource is invalid: `"string"`
|
||||
* **403 Forbidden**: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* **500 Internal Server Error**: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Unexpected Error! Please try again later."
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### MessageQuery
|
||||
|
||||
* **Description**: Model for pagination query parameters.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"startMessageId": "Guid?",
|
||||
"before": "int",
|
||||
"after": "int"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageResponse
|
||||
|
||||
* **Description**: Data transfer object for chat message details.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"recipientId": "Guid",
|
||||
"recipientType": "string",
|
||||
"encryptedContent": "string",
|
||||
"sentAt": "DateTime",
|
||||
"isEdited": "boolean",
|
||||
"editedAt": "DateTime?",
|
||||
"replyToMessageId": "Guid?",
|
||||
"mediaAttachments": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
],
|
||||
"reactions": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
],
|
||||
"messageViews": [
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### MediaAttachmentResponse
|
||||
|
||||
* **Description**: Data transfer object for media attachments in messages.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"mediaFileId": "Guid"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageReactionResponse
|
||||
|
||||
* **Description**: Data transfer object for message reactions.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"reactionCode": "string",
|
||||
"reactedAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
#### MessageViewResponse
|
||||
|
||||
* **Description**: Data transfer object for message view tracking.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"messageId": "Guid",
|
||||
"userId": "Guid",
|
||||
"viewedAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for negative values, total exceeding 100, or `InvalidOperationException`.
|
||||
* **Unauthorized Access**: Returns `403 Forbidden` for `UnauthorizedAccessException`.
|
||||
* **Resource Not Found**: Returns `400 Bad Request` for `NotFoundException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `UnauthorizedAccessException`, `NotFoundException`, `ArgumentException`, and `InvalidOperationException`.
|
||||
* Logs errors for unexpected exceptions.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for managing friendship-related operations, including
|
||||
searching for users and retrieving the list of friends for the current user.
|
||||
---
|
||||
|
||||
# FriendshipController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/friends`
|
||||
* **Authorize**: Requires authenticated user (`[Authorize]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Search</mark>
|
||||
|
||||
* **Description**: Searches for users based on a query string.
|
||||
* **Route**: `[GET] api/friends/search?query=`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Query Parameter**: `query` (string, required)
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of matching users.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>: If the query is empty.
|
||||
|
||||
```json
|
||||
"Query cannot be empty"
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal error during user search."
|
||||
}
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetFriends</mark>
|
||||
|
||||
* **Description**: Retrieves the list of friends for the authenticated user.
|
||||
* **Route**: `[GET] api/friends`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of the user's friends or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### UserDto
|
||||
|
||||
* **Description**: Data transfer object for user information.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"username": "string",
|
||||
"description": "string",
|
||||
"wasOnline": "DateTime",
|
||||
"iconId": "Guid"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for empty query.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `SearchUsersException`.
|
||||
* Logs errors for unexpected exceptions and `InvalidOperationException`.
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for querying friend request-related data, including
|
||||
incoming friend requests and responses to sent friend requests.
|
||||
---
|
||||
|
||||
# FriendsRequestQueryController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/friends`
|
||||
* **Authorize**: Requires authenticated user (`[Authorize]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">GetIncomingRequests</mark>
|
||||
|
||||
* **Description**: Retrieves a list of incoming friend requests for the authenticated user.
|
||||
* **Route**: `[GET] api/friends/requests`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of incoming friend requests or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">GetResponses</mark>
|
||||
|
||||
* **Description**: Retrieves a list of responses to the authenticated user's sent friend requests.
|
||||
* **Route**: `[GET] api/friends/responses`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**: None
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns a list of friend request responses or an empty list if none.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
]
|
||||
```
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error."
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### FriendshipDto
|
||||
|
||||
* **Description**: Data transfer object for friend request information.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Guid",
|
||||
"senderId": "Guid",
|
||||
"receiverId": "Guid",
|
||||
"status": "string",
|
||||
"createdAt": "DateTime"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `200 OK` with an empty list for `InvalidOperationException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `InvalidOperationException`.
|
||||
* Logs information for successful response retrieval.
|
||||
* Logs errors for unexpected exceptions.
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
description: Controller for uploading and downloading media files.
|
||||
---
|
||||
|
||||
# MediaController
|
||||
|
||||
### Controller Description
|
||||
|
||||
* **Route**: `api/media`
|
||||
* **Authorize**: Requires authenticated user with roles "User" or "Admin" (`[Authorize(Roles = "User,Admin")]`).
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### <mark style="color:$info;">Upload</mark>
|
||||
|
||||
* **Description**: Uploads a media file with associated metadata.
|
||||
* **Route**: `[POST] api/media/upload`
|
||||
* **HTTP Method**: `POST`
|
||||
* **Request**:
|
||||
* **Content-Type**: `multipart/form-data`
|
||||
* **Request Body**: `MediaUploadRequest` object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"fromFile": "IFormFile",
|
||||
"type": "MediaType",
|
||||
"mimeType": "string",
|
||||
"encryptedKey": "string"
|
||||
}
|
||||
```
|
||||
* **Constraints**: File size limit of 20 MB.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the upload result.
|
||||
|
||||
```json
|
||||
"string" // Media ID or similar result
|
||||
```
|
||||
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
||||
* If model validation fails.
|
||||
* If no file is uploaded: `"No file uploaded"`
|
||||
* If file exceeds 20 MB: `"File is too large"`
|
||||
* If MIME type is missing: `"Missing MIME type"`
|
||||
* If operation is invalid: `"string"`
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks authorization.
|
||||
|
||||
```json
|
||||
"string"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Internal server error"
|
||||
```
|
||||
|
||||
#### <mark style="color:$info;">Download</mark>
|
||||
|
||||
* **Description**: Downloads a media file by its ID.
|
||||
* **Route**: `[GET] api/media/download/{id}`
|
||||
* **HTTP Method**: `GET`
|
||||
* **Request**:
|
||||
* **Path Parameter**: `id` (Guid, required): ID of the media file.
|
||||
* **Responses**:
|
||||
* <mark style="color:$success;">**200 OK**</mark>: Returns the media file as a stream.
|
||||
* **Content-Type**: Matches `MimeType` of the media.
|
||||
* **Content-Disposition**: Includes `filename` from `FileName`.
|
||||
* <mark style="color:$danger;">**403 Forbidden**</mark>: If user lacks access.
|
||||
* No body.
|
||||
* <mark style="color:$danger;">**404 Not Found**</mark>: If media is not found.
|
||||
|
||||
```json
|
||||
"Media not found"
|
||||
```
|
||||
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
"Internal server error"
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
#### MediaUploadRequest
|
||||
|
||||
* **Description**: Model for media upload request data.
|
||||
* **Structure**:
|
||||
|
||||
```json
|
||||
{
|
||||
"fromFile": "IFormFile",
|
||||
"type": "MediaType",
|
||||
"mimeType": "string",
|
||||
"encryptedKey": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
* **Invalid User ID**: Handled by `ICurrentUserService`, aborts if invalid.
|
||||
* **Invalid Operations**: Returns `400 Bad Request` for `InvalidOperationException`.
|
||||
* **Unauthorized Access**: Returns `403 Forbidden` for `UnauthorizedAccessException`.
|
||||
* **Resource Not Found**: Returns `404 Not Found` for `KeyNotFoundException`.
|
||||
* **Unexpected Errors**: Caught and returned as `500 Internal Server Error`.
|
||||
|
||||
### Logging
|
||||
|
||||
* Logs warnings for `UnauthorizedAccessException`, `InvalidOperationException`, and `KeyNotFoundException`.
|
||||
* Logs information for successful file uploads.
|
||||
* Logs errors for unexpected exceptions during upload and download.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: >-
|
||||
Description: Controller for handling user online status updates by processing
|
||||
ping requests.
|
||||
---
|
||||
|
||||
# OnlinePingingController(не работает)
|
||||
|
||||
**Route**: `api/online`\
|
||||
**Authorize**: Requires "User" or "Admin" role
|
||||
|
||||
### <mark style="color:purple;">End Point {PATCH}</mark>
|
||||
|
||||
`[PATCH] api/online/ping`
|
||||
|
||||
#### Description
|
||||
|
||||
Updates the online status of the current user by sending a ping request.
|
||||
|
||||
**Request**
|
||||
|
||||
* **Content-Type**: `application/json`
|
||||
* **Request Body**: None
|
||||
|
||||
**Responses**
|
||||
|
||||
* **200 OK**: Ping processed successfully.
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
* **400 Bad Request**: If the user cannot be found in the database.
|
||||
|
||||
```json
|
||||
"User can't be found in our database."
|
||||
```
|
||||
* **403 Forbidden**: If the user is not authorized to perform the action.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Not authorized to perform this action."
|
||||
}
|
||||
```
|
||||
* **500 Internal Server Error**: Indicates an unexpected error.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Failed to send friend request."
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user