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,132 @@
+# Tag API
+
+> **Prefix:** `/api/v1/tags`, `/api/v1/admin/tag`
+
+Tags are used for categorizing blog posts.
+
+---
+
+## GET `/api/v1/tags`
+
+List all active tags.
+
+**Permission:** `PUBLIC`
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 1, "name": "دیابت", "slug": "diabat", "status": "active" },
+    { "id": 2, "name": "قلب", "slug": "ghalb", "status": "active" }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/admin/tags`
+
+List all tags 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": 10, "totalPages": 1, "currentPage": 1 }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+
+---
+
+## POST `/api/v1/admin/tag`
+
+Create a new tag.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "دیابت",
+  "slug": "diabat",
+  "status": "active"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | Tag name |
+| `slug` | string | ❌ | Auto-generated from name if omitted |
+| `status` | string | ❌ | `"active"` (default) or `"inactive"` |
+
+### Response `201`
+Tag 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/tag/{id}`
+
+Update a tag.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Tag ID |
+
+All fields optional.
+
+### Response `200`
+Updated tag object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Tag not found |
+
+---
+
+## DELETE `/api/v1/admin/tag/{id}`
+
+Delete a tag.
+
+**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 | Tag not found |