Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints
This commit is contained in:
hamed
@@ -0,0 +1,275 @@
|
||||
# Rating & Comments API
|
||||
|
||||
> **Prefix:** `/api/v1/rate`, `/api/v1/comment`, `/api/v1/like`
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/rate`
|
||||
|
||||
Submit a rating for a doctor.
|
||||
|
||||
**Permission:** `AUTH` — any authenticated user (typically after a completed appointment)
|
||||
|
||||
### Request Body (`application/json`)
|
||||
```json
|
||||
{
|
||||
"doctor_uuid": "550e8400-...",
|
||||
"score": 5
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Validation |
|
||||
|-------|------|----------|------------|
|
||||
| `doctor_uuid` | string (UUID) | ✅ | Must exist |
|
||||
| `score` | integer | ✅ | 1–5 |
|
||||
|
||||
### Response `201`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"uuid": "rate-uuid-...",
|
||||
"doctor_uuid": "...",
|
||||
"score": 5,
|
||||
"created_at": 1717000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
| `ERR_VALIDATION_001` | 422 | Score out of range |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/rate/{doctorUuid}`
|
||||
|
||||
Get average rating for a doctor.
|
||||
|
||||
**Permission:** `PUBLIC`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `doctorUuid` | string (UUID) | Doctor UUID |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"average": 4.3,
|
||||
"total": 47
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/comment`
|
||||
|
||||
Submit a comment/review for a doctor.
|
||||
|
||||
**Permission:** `AUTH`
|
||||
|
||||
> Comments require admin approval before appearing publicly.
|
||||
|
||||
### Request Body (`application/json`)
|
||||
```json
|
||||
{
|
||||
"doctor_uuid": "550e8400-...",
|
||||
"body": "پزشک بسیار مؤدب و متخصص بودند"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Validation |
|
||||
|-------|------|----------|------------|
|
||||
| `doctor_uuid` | string (UUID) | ✅ | Must exist |
|
||||
| `body` | string | ✅ | Min 10 chars |
|
||||
|
||||
### Response `201`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"uuid": "comment-uuid-...",
|
||||
"body": "پزشک بسیار مؤدب و متخصص بودند",
|
||||
"status": "pending",
|
||||
"created_at": 1717000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Comment Status Values:**
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `pending` | Awaiting admin review |
|
||||
| `approved` | Visible to public |
|
||||
| `rejected` | Not visible |
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
| `ERR_VALIDATION_001` | 422 | Body too short |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/comments/{doctorUuid}`
|
||||
|
||||
Get approved comments for a doctor.
|
||||
|
||||
**Permission:** `PUBLIC`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `doctorUuid` | string (UUID) | Doctor UUID |
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"uuid": "...",
|
||||
"body": "پزشک بسیار مؤدب...",
|
||||
"user": { "uuid": "...", "real_name": "علی" },
|
||||
"likes": 3,
|
||||
"status": "approved",
|
||||
"created_at": 1717000000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
|
||||
|
||||
---
|
||||
|
||||
## DELETE `/api/v1/comment/{uuid}`
|
||||
|
||||
Delete a comment.
|
||||
|
||||
**Permission:** `AUTH` — must be the comment author or `ROLE_ADMIN`
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{ "success": true, "data": { "message": "نظر حذف شد" } }
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_FORBIDDEN_001` | 403 | Not the author |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Comment not found |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/admin/comments/pending`
|
||||
|
||||
Get all pending comments waiting for review.
|
||||
|
||||
**Permission:** `ROLE_ADMIN`
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"uuid": "...",
|
||||
"body": "...",
|
||||
"doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
|
||||
"user": { "uuid": "...", "real_name": "..." },
|
||||
"status": "pending",
|
||||
"created_at": 1717000000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_AUTH_006` | 403 | Not admin |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/admin/comment/{uuid}/approve`
|
||||
|
||||
Approve a pending comment (makes it public).
|
||||
|
||||
**Permission:** `ROLE_ADMIN`
|
||||
|
||||
### Response `200`
|
||||
Updated comment object with `status: "approved"`.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_AUTH_006` | 403 | Not admin |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Comment not found |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/admin/comment/{uuid}/reject`
|
||||
|
||||
Reject a pending comment.
|
||||
|
||||
**Permission:** `ROLE_ADMIN`
|
||||
|
||||
### Response `200`
|
||||
Updated comment object with `status: "rejected"`.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_AUTH_006` | 403 | Not admin |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Comment not found |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/like/{commentUuid}`
|
||||
|
||||
Toggle like on a comment (like if not liked, unlike if already liked).
|
||||
|
||||
**Permission:** `AUTH`
|
||||
|
||||
### Path Parameters
|
||||
| Param | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `commentUuid` | string (UUID) | Comment UUID |
|
||||
|
||||
### Response `200` (unlike) or `201` (new like)
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"liked": true,
|
||||
"likes": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|------|------|-------------|
|
||||
| `ERR_AUTH_001` | 401 | Missing token |
|
||||
| `ERR_NOT_FOUND_001` | 404 | Comment not found |
|
||||
Reference in New Issue
Block a user