Tài liệu API cần có gì để lập trình viên tích hợp được mà không phải hỏi bạn?

Tài liệu tốt trả lời các câu hỏi theo đúng thứ tự mà lập trình viên đặt ra: mình thử được chưa, xác thực thế nào, và mỗi lời gọi làm gì?

Những thứ thiết yếu:

• Quickstart. Thực hiện lời gọi thành công đầu tiên trong vài phút, với lệnh curl copy-paste được và một sandbox key.
• Authentication. Cách lấy key hoặc token, header cần gửi, scope và cách xoay vòng credential.
• Reference. Mọi endpoint với parameter, schema request và response, cùng payload ví dụ thực tế. Sinh từ OpenAPI spec để không bị lệch.
• Khái niệm và hướng dẫn. Pagination, filtering, idempotency, rate limit, webhook và versioning, mỗi thứ giải thích một lần.
• Danh mục lỗi. Mỗi mã lỗi, nguyên nhân và cách khắc phục.
• Ví dụ bằng nhiều ngôn ngữ, tốt nhất lấy từ các SDK được sinh ra.
• Changelog và thông báo deprecation, kèm ngày tháng.

Cũng đáng có: console thử trực tiếp, trang trạng thái và kênh liên hệ hỗ trợ.

Chạy các ví dụ trong CI, để tài liệu không còn chạy được sẽ làm hỏng build. Tài liệu sai còn tệ hơn không có tài liệu.