Thiết lập API Specs

Role: Solution Architect 🏗️

API Specs lưu trữ Swagger/OpenAPI URL cho từng environment của System. Sau khi Sync, AIPD trích xuất danh sách endpoints và cho phép liên kết chúng vào Features — giúp AI Agent sinh tài liệu kỹ thuật với thông tin endpoint chính xác thay vì dùng placeholder.

Hướng dẫn thao tác

1. Trong System Management, chọn System từ danh sách bên trái.
2. Chuyển sang tab "API Specs".

---

Nhập Swagger URL

Tab hiển thị một card cho mỗi environment đã tạo (ví dụ: DEV, STAGING, PROD). Mỗi card có màu tương ứng với environment (xanh dương cho Dev, vàng cho Staging, đỏ cho Prod...).

Thực hiện cho từng environment:

1. Nhập URL đến file swagger.json hoặc openapi.yaml vào ô input của card tương ứng.

   • Placeholder: Enter the full URL to the swagger.json file...
   • Ví dụ: https://api.dev.yourapp.com/docs/swagger.json

2. Nhấn nút Save (icon đĩa mềm) trên card đó. Nút Save chỉ hiển thị active khi URL đã thay đổi so với giá trị đang lưu.

   • Thông báo thành công: "API Spec Saved — Swagger URL for [environment name] updated successfully."

3. Nhấn nút Sync (icon refresh/spinner) để trích xuất danh sách endpoints từ Swagger.

   • Trong lúc sync, icon chuyển sang spinner.
   • Thông báo thành công: "Swagger synced — Endpoints were extracted from the Swagger specification."
   • Thông báo lỗi: "Sync failed — Unable to sync endpoints from the Swagger specification."

---

Các thao tác bổ sung trên mỗi card

Nút	Hành động
Open Link (icon link)	Mở Swagger URL trong tab mới
Copy URL (icon copy)	Sao chép URL vào clipboard — hiện thông báo "URL copied to clipboard"
Save (icon đĩa mềm)	Lưu URL — chỉ active khi URL đã thay đổi
Sync (icon refresh)	Trích xuất endpoints từ Swagger — chỉ active khi đã có URL

---

Sau khi Sync thành công

Các endpoints được trích xuất sẽ xuất hiện trong dropdown "Associated Endpoints" khi tạo hoặc chỉnh sửa Feature (tab Features). Mỗi endpoint hiển thị dưới dạng METHOD /path với màu theo HTTP method:

Method	Màu
GET	Xanh dương
POST	Xanh lá
PUT	Cam
DELETE	Đỏ
PATCH	Tím

---

Trường hợp chưa có Swagger

Nếu team chưa expose Swagger endpoint, có thể:

• Bỏ qua bước này và quay lại điền sau khi service đã có Swagger.
• Endpoints trong Features sẽ để trống — AI vẫn sinh được tài liệu nhưng sẽ thiếu thông tin API cụ thể.

URL Swagger động

Nếu team dùng NestJS, Spring Boot, hoặc FastAPI với auto-generate Swagger, URL thường có dạng cố định (/api/docs, /swagger-ui, /openapi.json). Dùng URL đó — mỗi khi deploy bản mới, Sync lại để AIPD cập nhật endpoint mới nhất.

Bước tiếp theo

Sau khi thiết lập API Specs, chuyển sang bước cuối cùng 06 — Khởi tạo System Foundation để soạn tài liệu kỹ thuật nền tảng cho AI Agent.