Mục tiêu

Tạo tài liệu API OpenAPI/Swagger chuyên nghiệp, chi tiết và dễ bảo trì cho các backend services. Giúp developers hiểu rõ cách sử dụng API, các endpoint, tham số, response, và xử lý lỗi.

Khi nào nên dùng

• Bạn cần tài liệu hóa một API mới hoặc cập nhật tài liệu API hiện tại
• Muốn chuẩn hóa định dạng tài liệu API theo tiêu chuẩn OpenAPI 3.0
• Cần tạo tài liệu chi tiết cho các endpoint phức tạp với nhiều tham số và response
• Muốn tự động hóa quá trình tạo tài liệu API từ mô tả chức năng
• Cần tài liệu API hỗ trợ đa ngôn ngữ hoặc đa phiên bản

Hướng dẫn tùy biến

• Thay thế tên service, endpoint, và tham số theo API thực tế của bạn
• Điều chỉnh mô tả, ví dụ, và giá trị mặc định phù hợp với logic business
• Bổ sung các authentication method, rate limiting, hoặc security scheme cụ thể
• Mở rộng schema dữ liệu với các field bổ sung hoặc nested objects
• Thêm các ví dụ request/response thực tế để minh họa rõ hơn

Lưu ý

• Đảm bảo tất cả endpoint, tham số, và response được mô tả đầy đủ
• Sử dụng HTTP status code chuẩn (200, 201, 400, 401, 404, 500)
• Cung cấp ví dụ request/response cụ thể cho mỗi endpoint
• Định nghĩa rõ ràng các error response và mã lỗi
• Cập nhật tài liệu khi có thay đổi API để tránh confusion