Skip to content

Api doc #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hadeer-r merged 1 commit into from
Sep 10, 2025
Merged

Api doc #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 149 additions & 0 deletions APIs/Auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Endpoints for Authentication

### Register
POST: `/api/Auth/register`

**Request**
```json
{
"name": "string",
"username": "string",
"email": "string",
"bio": "string",
"avatarPath": "string",
"passwrod": "string",
"lastSeen": "2025-09-06T22:27:00.026Z"
Comment on lines +14 to +15
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix “passwrod” typo in request body.

User-facing docs.

-  "passwrod": "string",
+  "password": "string",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"passwrod": "string",
"lastSeen": "2025-09-06T22:27:00.026Z"
"password": "string",
"lastSeen": "2025-09-06T22:27:00.026Z"
🤖 Prompt for AI Agents 
In APIs/Auth.md around lines 14 to 15, the request body contains a typo
"passwrod": change the key to the correct "password" in the JSON example; update
any other occurrences of "passwrod" in this file (and related docs) to
"password" to keep examples consistent and user-facing documentation accurate.

}
```
**Response**

Status Code: 200

```json
{
"success": true,
"errors": [
"string"
],
"data": {
"isAuthenticated": true,
"token": "string",
"refreshToken": {
"token": "string",
"expireOn": "2025-09-06T22:57:05.109Z",
"isExpired": true,
"revokedOn": "2025-09-06T22:57:05.109Z",
"isActive": true,
"createdOn": "2025-09-06T22:57:05.109Z"
},
"user": {
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T22:57:05.109Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
}
}
```

-----
### Login
POST: `/api/Auth/login`

**Request**
```json
{
"email": "string",
"password": "string"

}
```
**Response**

Status Code: 200

```json
{
"success": true,
"errors": [
"string"
],
"data": {
"isAuthenticated": true,
"token": "string",
"refreshToken": {
"token": "string",
"expireOn": "2025-09-06T22:57:05.109Z",
"isExpired": true,
"revokedOn": "2025-09-06T22:57:05.109Z",
"isActive": true,
"createdOn": "2025-09-06T22:57:05.109Z"
},
"user": {
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T22:57:05.109Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
}
}
```

------
### Refresh Token
POST: `/api/Auth/refresh-token/{id}`
Description: refersh token when jwt token is expired

**Response**
Comment on lines +96 to +101
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Clarify refresh-token description and fix spelling. Align with controller behavior.

If you accept making the action anonymous (suggested in code), reflect that here and note cookie requirement.

-### Refresh Token
-POST: `/api/Auth/refresh-token/{id}`
-Description: refersh token when jwt token is expired
+### Refresh Token
+POST: `/api/Auth/refresh-token/{id}`
+Description: Refresh the access token using the HTTP-only `refreshToken` cookie.
+Auth: No Authorization header required (endpoint validates the refresh token).

If you keep [Authorize] on the action instead, change “Auth” to “Requires valid Bearer token” and note the access token must still be valid.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
------
### Refresh Token
POST: `/api/Auth/refresh-token/{id}`
Description: refersh token when jwt token is expired
**Response**
------
### Refresh Token
POST: `/api/Auth/refresh-token/{id}`
Description: Refresh the access token using the HTTP-only `refreshToken` cookie.
Auth: No Authorization header required (endpoint validates the refresh token).
**Response**
🧰 Tools
🪛 LanguageTool

[grammar] ~97-~97: There might be a mistake here.
Context: ... } } } ``` ------ ### Refresh Token POST: /api/Auth/refresh-token/{id} Des...

(QB_NEW_EN)

[grammar] ~98-~98: There might be a mistake here.
Context: ...ken POST: /api/Auth/refresh-token/{id} Description: refersh token when jwt toke...

(QB_NEW_EN)

[grammar] ~99-~99: Ensure spelling is correct
Context: ...i/Auth/refresh-token/{id}` Description: refersh token when jwt token is expired **Resp...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
In APIs/Auth.md around lines 96 to 101, the Refresh Token section has a typo
("refersh") and an inaccurate description that doesn't reflect controller
behavior; update the heading and description to "Refresh Token", fix spelling,
and then either (A) if the controller action is made anonymous, state "Anonymous
access" and note that the request requires the refresh token cookie to be
present (and include the POST path `/api/Auth/refresh-token/{id}`), or (B) if
the action remains protected with [Authorize], change the descriptor to
"Requires valid Bearer token" and explicitly state that the access token must
still be valid while describing that the endpoint exchanges the refresh token
(from cookie) for a new access token; ensure the docs clearly state the cookie
requirement in both cases.


Status Code: 200
```json
{
"success": true,
"errors": [
"string"
],
"data": {
"isAuthenticated": true,
"token": "string",
"refreshToken": {
"token": "string",
"expireOn": "2025-09-06T22:57:05.109Z",
"isExpired": true,
"revokedOn": "2025-09-06T22:57:05.109Z",
"isActive": true,
"createdOn": "2025-09-06T22:57:05.109Z"
},
"user": {
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T22:57:05.109Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
}
}
```

---------
### Logout
POST: `/api/Auth/logout/{id}`
Description: refersh token when jwt token is expired

**Response**

Comment on lines +134 to +139
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix Logout description and spelling.

-### Logout
-POST: `/api/Auth/logout/{id}`
-Description: refersh token when jwt token is expired
+### Logout
+POST: `/api/Auth/logout/{id}`
+Description: Revoke the refresh token and clear the cookie.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Logout
POST: `/api/Auth/logout/{id}`
Description: refersh token when jwt token is expired
**Response**
### Logout
POST: `/api/Auth/logout/{id}`
Description: Revoke the refresh token and clear the cookie.
**Response**
🧰 Tools
🪛 LanguageTool

[grammar] ~134-~134: There might be a mistake here.
Context: ... 0 } } } ``` --------- ### Logout POST: /api/Auth/logout/{id} Descriptio...

(QB_NEW_EN)

[grammar] ~135-~135: There might be a mistake here.
Context: ...### Logout POST: /api/Auth/logout/{id} Description: refersh token when jwt toke...

(QB_NEW_EN)

[grammar] ~136-~136: Ensure spelling is correct
Context: ...T: /api/Auth/logout/{id} Description: refersh token when jwt token is expired **Resp...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
In APIs/Auth.md around lines 134 to 139, the Logout endpoint description is
incorrect and misspelled: change "refersh token when jwt token is expired" to a
clear, correct description such as "Invalidates the user's refresh token and
logs out the user" (or "Revokes the refresh token and ends the session"),
correct the spelling of "refresh", and optionally add a brief Response summary
(e.g., 200 on success, 401/404 on errors) to replace the empty **Response**
section.

Status Code: 200
```json
{
"success": true,
"errors": [
"string"
],
"data": true
}
```
105 changes: 105 additions & 0 deletions APIs/User.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Endpoints for User
### Get current user Profile
GET: `/api/User/profile`

**Response**

Status Code: 200

```json
{
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T23:04:42.634Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
```

---------
### Get User By
GET: `/api/User/profile/{userId}`
Description: Get user by id

**Response**

Status Code: 200

```json
{
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T23:04:42.634Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
```

---------
### Delete current user
Delete: `/api/User/profile/{userId}`

**Response**
Status Code: 200

---------
### Update User
POST: `/api/User/profile/update/{userId}`

**Request**
```json
{
"name": "string",
"bio": "string",
"avatarPath": "string"
}
```

**Response**

Status Code: 200

```json
{
"name": "string",
"email": "string",
"lastSeen": "2025-09-06T23:10:21.411Z",
"bio": "string",
"avatarPath": "string",
"followerCount": 0
}
```

---------
### Follow
POST: `/api/User/profile/{followerId}/follow/{targetUserId}`

**Response**

Status Code: 200

---------
### Unfollow
POST: `/api/User/profile/{followerId}/unfollow/{targetUserId}`

**Response**

Status Code: 200

---------
### Update Password
GET: `/api/User/profile/update/pass/{userId}`

**Request**
```json
{
"currentPassword": "string",
"updatedPassword": "string"
}
```
Comment on lines +93 to +101
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Method mismatch: docs show GET but code uses POST for Update Password.

Align with controller.

-### Update Password
-GET: `/api/User/profile/update/pass/{userId}`
+### Update Password
+POST: `/api/User/profile/update/pass/{userId}`
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
GET: `/api/User/profile/update/pass/{userId}`
**Request**
```json
{
"currentPassword": "string",
"updatedPassword": "string"
}
```
### Update Password
POST: `/api/User/profile/update/pass/{userId}`
**Request**
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

96-96: Horizontal rule style
Expected: -----; Actual: ------

(MD035, hr-style)

101-101: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

🤖 Prompt for AI Agents 
In APIs/User.md around lines 93 to 101 the HTTP method for the Update Password
endpoint is listed as GET but the controller uses POST; update the documentation
to use POST for the endpoint (e.g., POST
`/api/User/profile/update/pass/{userId}`), ensure the Request example stays
under the POST method, and adjust any related sample requests or headers in this
section to match the controller's POST behavior.


**Response**

Status Code: 200
2 changes: 1 addition & 1 deletion AskFm/AskFm.API/Controllers/AuthController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ public async Task<IActionResult> Login(LoginDTO login)
return Ok(result);
}

[HttpGet]
[HttpPost]
[Route("refresh-token/{id}")]
[Authorize(AuthenticationSchemes = "Bearer")]
public async Task<IActionResult> RefreshToken(int id)
Comment on lines +59 to 62
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Refresh endpoint requires [Authorize], defeating refresh when access token is expired.

Either make this action anonymous (recommended) or document that an unexpired access token is required (which undermines refresh UX).

-    [HttpPost]
-    [Route("refresh-token/{id}")]
-    [Authorize(AuthenticationSchemes = "Bearer")]
+    [HttpPost]
+    [Route("refresh-token/{id}")]
+    [AllowAnonymous]
     public async Task<IActionResult> RefreshToken(int id)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
[HttpPost]
[Route("refresh-token/{id}")]
[Authorize(AuthenticationSchemes = "Bearer")]
public async Task<IActionResult> RefreshToken(int id)
[HttpPost]
[Route("refresh-token/{id}")]
[AllowAnonymous]
public async Task<IActionResult> RefreshToken(int id)
🤖 Prompt for AI Agents 
In AskFm/AskFm.API/Controllers/AuthController.cs around lines 59-62, the
RefreshToken endpoint is decorated with [Authorize] which forces a valid access
token and prevents token refresh when the access token is expired; remove or
replace [Authorize(AuthenticationSchemes = "Bearer")] with [AllowAnonymous] (or
remove the attribute) so the endpoint can be called without a valid access
token, then ensure the method explicitly validates the provided refresh token
(from body/cookie) and the user id, handles invalid/expired refresh tokens with
proper 401/400 responses, and keeps other security checks (e.g.,
rotating/storing refresh tokens, revocation) intact.

Expand Down
2 changes: 1 addition & 1 deletion AskFm/AskFm.API/Controllers/UserController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ public async Task<IActionResult> UpdateUserAsync(int userId, UpdateUserDTO updat
}

var userRead = await _userService.GetUserByIdAsync(userId);
return Ok(userRead);
return Ok(userRead.Data);
}
Comment on lines 74 to 76
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Return only the inner payload — also handle post-update read failures.

Good switch to returning userRead.Data. Add a guard so a failed read doesn’t return 200 with null (or mask an error).

-        var userRead = await _userService.GetUserByIdAsync(userId);
-        return Ok(userRead.Data);
+        var userRead = await _userService.GetUserByIdAsync(userId);
+        if (!userRead.success || userRead.Data is null)
+        {
+            return StatusCode(StatusCodes.Status500InternalServerError, "Failed to load updated user.");
+        }
+        return Ok(userRead.Data);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
var userRead = await _userService.GetUserByIdAsync(userId);
return Ok(userRead);
return Ok(userRead.Data);
}
var userRead = await _userService.GetUserByIdAsync(userId);
if (!userRead.success || userRead.Data is null)
{
return StatusCode(StatusCodes.Status500InternalServerError, "Failed to load updated user.");
}
return Ok(userRead.Data);
}


[HttpDelete]
Expand Down
Loading