Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints

2026-06-11 10:27:27 +03:30
parent e88ae9bf9c
commit cced85456a
22 changed files with 5691 additions and 0 deletions
@@ -0,0 +1,146 @@
+# Doctor Service API
+
+> **Prefix:** `/api/v1/doctor-services`, `/api/v1/admin/doctor-service`
+
+---
+
+## GET `/api/v1/doctor-services`
+
+List all active doctor services.
+
+**Permission:** `PUBLIC`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `specialty_id` | integer | ❌ | Filter by parent specialty |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "نوار قلب (ECG)",
+      "slug": "navar-ghalb",
+      "specialty_id": 1,
+      "status": "active",
+      "weight": 5
+    }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/admin/doctor-services`
+
+List all services with pagination (admin view).
+
+**Permission:** `ROLE_ADMIN`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | integer | ❌ | Default: 1 |
+| `limit` | integer | ❌ | Default: 20 |
+| `search` | string | ❌ | Search in name |
+| `specialty_id` | integer | ❌ | Filter by specialty |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "meta": { "totalRecords": 30, "totalPages": 2, "currentPage": 1 }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+
+---
+
+## POST `/api/v1/admin/doctor-service`
+
+Create a new doctor service.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "نوار قلب (ECG)",
+  "slug": "navar-ghalb",
+  "specialty_id": 1,
+  "status": "active",
+  "weight": 5
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | Service name |
+| `slug` | string | ❌ | Auto-generated from name if omitted |
+| `specialty_id` | integer | ❌ | Link to specialty |
+| `status` | string | ❌ | `"active"` or `"inactive"` |
+| `weight` | integer | ❌ | Sort weight |
+
+### Response `201`
+Service object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_VALIDATION_002` | 422 | Missing name |
+
+---
+
+## PATCH `/api/v1/admin/doctor-service/{id}`
+
+Update a doctor service.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Service ID |
+
+All body fields optional.
+
+### Response `200`
+Updated service object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Service not found |
+
+---
+
+## DELETE `/api/v1/admin/doctor-service/{id}`
+
+Delete a doctor service.
+
+**Permission:** `ROLE_ADMIN`
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "خدمت پزشکی حذف شد" } }
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Service not found |