---
name: ApiDocumentation
description: Hướng dẫn viết tài liệu API chuẩn cho dự án (dựa trên mẫu API_FuelCardManagement).
---

# API Documentation Skill

Tài liệu này hướng dẫn cách viết tài liệu API chuẩn cho dự án LADA, đảm bảo tính nhất quán và đầy đủ thông tin cho Frontend và Mobile team.

## 1. Cấu trúc chung của file MarkDown

- **Tên file**: Đặt tên theo format `API_[FeatureName].md`. Ví dụ: `API_FuelCardManagement.md`.
- **Vị trí**: Lưu trong thư mục `Ladaer.BackEnd/Ladaer.BackEnd/Docs`.
- **Header**: Sử dụng H1 cho tên module.

```markdown
# API Documentation - [Tên Module]

## Mục lục
1. [Nhóm chức năng A](#1-nhóm-chức-năng-a)
2. [Nhóm chức năng B](#2-nhóm-chức-năng-b)
...

---

## 1. Nhóm chức năng A
...
```

## 2. Cấu trúc chi tiết từng Endpoint

Mỗi API endpoint cần được mô tả theo mẫu dưới đây:

### Tiêu đề
Sử dụng H3 cho tên hành động. Format: `### [Số thứ tự]. [Tên hành động]`

### Thông tin cơ bản
- **Endpoint**: Method + URL (Ví dụ: `POST /api/FuelCard/Search`)
- **Authorization**: Quyền cần thiết (Ví dụ: `FuelCard.Search`)

### Request
Mô tả params (Query String) hoặc Body.

**Trường hợp 1: Request Body (JSON)**
Sử dụng code block `json` để ví dụ mẫu request.

```markdown
**Request Body:**
\`\`\`json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 15
  },
  "Search": {
    "PredicateObject": {
      "Keyword": "abc"
    }
  },
  "Sort": {
    "Predicate": "CreatedTime",
    "Reverse": true
  }
}
\`\`\`
```

**Trường hợp 2: Form-Data (Upload file)**
Liệt kê các trường dưới dạng list.

```markdown
**Request (Form-Data):**
- `Id` (int, required): ID bản ghi
- `Files` (IFormFile[], required): Danh sách file
```

### Parameters Detail
Giải thích chi tiết các tham số quan trọng nếu cần.

```markdown
**Request Parameters:**
- `Status` (int): 1=Active, 2=Inactive
- `Note`: Ghi chú (max 1000 chars)
```

### Response
Mô tả kết quả trả về bằng JSON mẫu.

```markdown
**Response:**
\`\`\`json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": { ... }
}
\`\`\`
```

## 3. Sử dụng Alerts cho thông tin quan trọng

Sử dụng GitHub Alerts style để làm nổi bật các lưu ý:

- **NOTE**: Thông tin bổ sung, giải thích logic nghiệp vụ.
- **IMPORTANT**: Các quy tắc bắt buộc, logic quan trọng.
- **TIP**: Mẹo sử dụng API hiệu quả.

**Ví dụ:**

```markdown
> [!NOTE]
> **Logic tính toán**
> Hệ thống sẽ tự động tính toán số lượng dựa trên đơn giá.

> [!IMPORTANT]
> **Quy tắc validate**
> Không được phép xóa bản ghi đã có phát sinh giao dịch.
```

## 4. Quy tắc Naming Convention (Quan trọng)

> [!IMPORTANT]
> **PascalCase cho JSON Property**
> Trong .NET Backend của dự án này, mặc định JSON Serializer sử dụng **PascalCase**.
> - **ĐÚNG**: `UserName`, `PhoneNumber`, `CreatedTime`
> - **SAI**: `userName`, `phoneNumber`, `created_time`
>
> Khi viết ví dụ JSON (Request/Response), **BẮT BUỘC** phải sử dụng PascalCase cho các key để khớp với DTO C#.

## 5. Checklist kiểm tra tài liệu

Trước khi commit tài liệu API, hãy kiểm tra:
- [ ] Endpoint URL chính xác chưa?
- [ ] Authorization Token/Role đã đúng chưa?
- [ ] **JSON Property đã dùng PascalCase chưa?** (Rất quan trọng)
- [ ] JSON mẫu có hợp lệ (valid syntax) không?
- [ ] Đã mô tả đủ các trường input/output quan trọng chưa?
- [ ] Đã có các lưu ý nghiệp vụ (nếu có logic phức tạp) chưa?
