Mục tiêu

Bộ prompt này giúp bạn tạo ra tài liệu API RESTful hoàn chỉnh và chuẩn xác theo đặc tả OpenAPI 3.0, tiết kiệm hàng giờ viết tay và giảm thiểu sai sót trong quá trình tài liệu hóa hệ thống backend.

• Sinh tài liệu OpenAPI 3.0 dạng YAML hoặc JSON cho từng endpoint hoặc toàn bộ API
• Định nghĩa đầy đủ request body, query params, path params, headers và response schema
• Chuẩn hóa error response theo RFC 7807 (Problem Details)
• Tích hợp mô tả authentication: Bearer JWT, API Key, OAuth2
• Tạo ví dụ request/response thực tế, dễ hiểu cho developer tiêu thụ API

Khi nào nên dùng

• Bắt đầu dự án mới và cần thiết lập tài liệu API từ đầu theo chuẩn
• Refactor hoặc nâng cấp tài liệu API cũ lên OpenAPI 3.0
• Onboarding developer mới cần tài liệu rõ ràng, đầy đủ
• Chuẩn bị tài liệu trước khi tích hợp với frontend hoặc bên thứ ba
• Code review tài liệu API để đảm bảo tính nhất quán trong toàn dự án

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

Mỗi prompt có các placeholder được đánh dấu bằng dấu ngoặc vuông [như thế này]. Bạn chỉ cần thay thế chúng bằng thông tin thực tế của dự án:

1. Thay [tên resource] bằng tên đối tượng nghiệp vụ, ví dụ: User, Order, Product
2. Thay [mô tả ngắn] bằng mục đích của API hoặc endpoint cụ thể
3. Thay [các trường dữ liệu] bằng danh sách field thực tế kèm kiểu dữ liệu
4. Chỉ định ngôn ngữ backend nếu muốn AI gợi ý convention phù hợp (Node.js, Django, Spring Boot…)
5. Yêu cầu output dạng YAML hoặc JSON tùy theo công cụ bạn đang dùng

Lưu ý

• Luôn review kết quả AI trước khi đưa vào production, đặc biệt phần security scheme
• Với API phức tạp nhiều endpoint, nên chạy từng nhóm resource thay vì toàn bộ một lúc
• Kết quả YAML có thể paste trực tiếp vào Swagger Editor (editor.swagger.io) để kiểm tra tính hợp lệ
• Nếu dự án dùng API Gateway (AWS, Kong, Apigee), hỏi thêm AI về các extension x-vendor phù hợp