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,162 @@
+# Specialty API
+
+> **Prefix:** `/api/v1/specialties`, `/api/v1/admin/specialty`
+
+---
+
+## GET `/api/v1/specialties`
+
+List all medical specialties.
+
+**Permission:** `PUBLIC`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `parent_id` | integer | ❌ | Filter to sub-specialties of a parent |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "قلب و عروق",
+      "slug": "ghalb-va-oroug",
+      "parent_id": null,
+      "status": "active",
+      "weight": 10
+    },
+    {
+      "id": 5,
+      "name": "فوق تخصص قلب",
+      "slug": "fowgh-takhassos-ghalb",
+      "parent_id": 1,
+      "status": "active",
+      "weight": 5
+    }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/admin/specialties`
+
+List all specialties with pagination (admin view — includes inactive).
+
+**Permission:** `ROLE_ADMIN`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | integer | ❌ | Default: 1 |
+| `limit` | integer | ❌ | Default: 20 |
+| `search` | string | ❌ | Search in name |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "meta": { "totalRecords": 50, "totalPages": 3, "currentPage": 1 }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+
+---
+
+## POST `/api/v1/admin/specialty`
+
+Create a new specialty.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "قلب و عروق",
+  "slug": "ghalb-va-oroug",
+  "parent_id": null,
+  "status": "active",
+  "weight": 10
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | Specialty name |
+| `slug` | string | ❌ | Auto-generated from name if omitted |
+| `parent_id` | integer | ❌ | Parent specialty ID (for sub-specialties) |
+| `status` | string | ❌ | `"active"` (default) or `"inactive"` |
+| `weight` | integer | ❌ | Sort weight |
+
+### Response `201`
+Specialty 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/specialty/{id}`
+
+Update a specialty.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Specialty ID |
+
+### Request Body (all optional)
+```json
+{
+  "name": "قلب و عروق ویرایش‌شده",
+  "status": "inactive",
+  "weight": 20,
+  "parent_id": null,
+  "slug": "new-slug"
+}
+```
+
+### Response `200`
+Updated specialty object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Specialty not found |
+
+---
+
+## DELETE `/api/v1/admin/specialty/{id}`
+
+Delete a specialty.
+
+**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 | Specialty not found |