From 1fe6e015fc8784ab280cd30561fe6550d58ff263 Mon Sep 17 00:00:00 2001 From: Artemy <109195690+stalcker2288969@users.noreply.github.com> Date: Thu, 24 Jul 2025 20:35:50 +0700 Subject: [PATCH] rework docs --- .../hubresult-less-than-t-greater-than.md | 0 .../endpoints}/authentication/README.md | 0 .../authentication/authcontroller.md | 0 .../authentication/refreshcontroller.md | 0 .../endpoints}/chatloadcontroller.md | 0 docs/endpoints/friendshipcontroller.md | 114 ++++++++++++++++++ .../friendsrequestquerycontroller.md | 109 +++++++++++++++++ .../endpoints}/mediacontroller.md | 0 .../onlinepingingcontroller-ne-rabotaet.md | 0 {friendshub => docs/friendshub}/README.md | 0 .../friendshub}/friendshub-client-java.md | 0 {signalr => docs/signalr}/chathub.md | 0 {signalr => docs/signalr}/presencehub.md | 0 13 files changed, 223 insertions(+) rename {code-docs => docs/code-docs}/hubresult-less-than-t-greater-than.md (100%) rename {endpoints => docs/endpoints}/authentication/README.md (100%) rename {endpoints => docs/endpoints}/authentication/authcontroller.md (100%) rename {endpoints => docs/endpoints}/authentication/refreshcontroller.md (100%) rename {endpoints => docs/endpoints}/chatloadcontroller.md (100%) create mode 100644 docs/endpoints/friendshipcontroller.md create mode 100644 docs/endpoints/friendsrequestquerycontroller.md rename {endpoints => docs/endpoints}/mediacontroller.md (100%) rename {endpoints => docs/endpoints}/onlinepingingcontroller-ne-rabotaet.md (100%) rename {friendshub => docs/friendshub}/README.md (100%) rename {friendshub => docs/friendshub}/friendshub-client-java.md (100%) rename {signalr => docs/signalr}/chathub.md (100%) rename {signalr => docs/signalr}/presencehub.md (100%) diff --git a/code-docs/hubresult-less-than-t-greater-than.md b/docs/code-docs/hubresult-less-than-t-greater-than.md similarity index 100% rename from code-docs/hubresult-less-than-t-greater-than.md rename to docs/code-docs/hubresult-less-than-t-greater-than.md diff --git a/endpoints/authentication/README.md b/docs/endpoints/authentication/README.md similarity index 100% rename from endpoints/authentication/README.md rename to docs/endpoints/authentication/README.md diff --git a/endpoints/authentication/authcontroller.md b/docs/endpoints/authentication/authcontroller.md similarity index 100% rename from endpoints/authentication/authcontroller.md rename to docs/endpoints/authentication/authcontroller.md diff --git a/endpoints/authentication/refreshcontroller.md b/docs/endpoints/authentication/refreshcontroller.md similarity index 100% rename from endpoints/authentication/refreshcontroller.md rename to docs/endpoints/authentication/refreshcontroller.md diff --git a/endpoints/chatloadcontroller.md b/docs/endpoints/chatloadcontroller.md similarity index 100% rename from endpoints/chatloadcontroller.md rename to docs/endpoints/chatloadcontroller.md diff --git a/docs/endpoints/friendshipcontroller.md b/docs/endpoints/friendshipcontroller.md new file mode 100644 index 0000000..4ba6894 --- /dev/null +++ b/docs/endpoints/friendshipcontroller.md @@ -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 + +#### Search + +* **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**: + * **200 OK**: Returns a list of matching users. + + ```json + [ + { + "id": "Guid", + "username": "string", + "description": "string", + "wasOnline": "DateTime", + "iconId": "Guid" + } + ] + ``` + * **400 Bad Request**: If the query is empty. + + ```json + "Query cannot be empty" + ``` + * **403 Forbidden**: If user lacks authorization. + + ```json + "string" + ``` + * **500 Internal Server Error**: Indicates an unexpected error. + + ```json + { + "error": "Internal error during user search." + } + ``` + +#### GetFriends + +* **Description**: Retrieves the list of friends for the authenticated user. +* **Route**: `[GET] api/friends` +* **HTTP Method**: `GET` +* **Request**: None +* **Responses**: + * **200 OK**: 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" + } + ] + ``` + * **403 Forbidden**: If user lacks authorization. + + ```json + "string" + ``` + * **500 Internal Server Error**: 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`. diff --git a/docs/endpoints/friendsrequestquerycontroller.md b/docs/endpoints/friendsrequestquerycontroller.md new file mode 100644 index 0000000..0af2473 --- /dev/null +++ b/docs/endpoints/friendsrequestquerycontroller.md @@ -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 + +#### GetIncomingRequests + +* **Description**: Retrieves a list of incoming friend requests for the authenticated user. +* **Route**: `[GET] api/friends/requests` +* **HTTP Method**: `GET` +* **Request**: None +* **Responses**: + * **200 OK**: Returns a list of incoming friend requests or an empty list if none. + + ```json + [ + { + "id": "Guid", + "senderId": "Guid", + "receiverId": "Guid", + "status": "string", + "createdAt": "DateTime" + } + ] + ``` + * **403 Forbidden**: If user lacks authorization. + + ```json + "string" + ``` + * **500 Internal Server Error**: Indicates an unexpected error. + + ```json + { + "error": "Internal server error." + } + ``` + +#### GetResponses + +* **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**: + * **200 OK**: Returns a list of friend request responses or an empty list if none. + + ```json + [ + { + "id": "Guid", + "senderId": "Guid", + "receiverId": "Guid", + "status": "string", + "createdAt": "DateTime" + } + ] + ``` + * **403 Forbidden**: If user lacks authorization. + + ```json + "string" + ``` + * **500 Internal Server Error**: 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. diff --git a/endpoints/mediacontroller.md b/docs/endpoints/mediacontroller.md similarity index 100% rename from endpoints/mediacontroller.md rename to docs/endpoints/mediacontroller.md diff --git a/endpoints/onlinepingingcontroller-ne-rabotaet.md b/docs/endpoints/onlinepingingcontroller-ne-rabotaet.md similarity index 100% rename from endpoints/onlinepingingcontroller-ne-rabotaet.md rename to docs/endpoints/onlinepingingcontroller-ne-rabotaet.md diff --git a/friendshub/README.md b/docs/friendshub/README.md similarity index 100% rename from friendshub/README.md rename to docs/friendshub/README.md diff --git a/friendshub/friendshub-client-java.md b/docs/friendshub/friendshub-client-java.md similarity index 100% rename from friendshub/friendshub-client-java.md rename to docs/friendshub/friendshub-client-java.md diff --git a/signalr/chathub.md b/docs/signalr/chathub.md similarity index 100% rename from signalr/chathub.md rename to docs/signalr/chathub.md diff --git a/signalr/presencehub.md b/docs/signalr/presencehub.md similarity index 100% rename from signalr/presencehub.md rename to docs/signalr/presencehub.md