Tôi sẽ viết tài liệu API rõ ràng để các nhà phát triển của bạn có thể làm theo ngay từ ngày đầu tiên

Tại sao hầu hết các tài liệu API thất bại

Chúng mô tả các điểm cuối và bỏ qua những phần thực sự ngăn cản mọi người: cách xác thực, một yêu cầu thực tế trông như thế nào, lỗi có nghĩa là gì và phải làm gì với nó. Người đọc sau đó mở một phiếu hỗ trợ, đó là chi phí mà tài liệu tồn tại để loại bỏ.

Cách tôi viết nó

Từ nguồn, không phải từ trí nhớ. Tôi đọc các tuyến đường, lớp xác thực và trình xử lý lỗi, sau đó tự gọi API bằng thông tin xác thực thực tế. Mọi ví dụ trong tài liệu là một yêu cầu tôi đã thực hiện và một phản hồi tôi đã nhận được — không có tải trọng được tạo ra, không có mã trạng thái mà điểm cuối không bao giờ trả về.

Tài liệu chứa gì

• Xác thực: lấy mã thông báo, làm mới nó và điều gì xảy ra khi nó hết hạn giữa phiên.
• Mọi điểm cuối với các tham số, một yêu cầu ví dụ hoàn chỉnh và hình dạng phản hồi thực tế.
• Một tham chiếu lỗi ánh xạ từng mã lỗi đến một nguyên nhân và một cách khắc phục, thay vì chỉ lặp lại thông báo.
• Một lộ trình bắt đầu giúp nhà phát triển mới từ con số không đến một cuộc gọi thành công trong vòng chưa đầy mười phút.
• Giới hạn tốc độ, phân trang, webhook và tính bất biến được giải thích ở những nơi chúng thực sự áp dụng.

Định dạng

Markdown trong kho lưu trữ của bạn, được cấu trúc cho OpenAPI hoặc một trang web tài liệu — bất cứ thứ gì bạn thực sự sẽ duy trì. Các mẫu mã bằng các ngôn ngữ mà người dùng của bạn hỏi, được xác minh bằng cách chạy chúng. Bộ sưu tập Postman hoặc tương tự được bao gồm nếu bạn muốn.

Những gì tôi cần

Truy cập kho lưu trữ hoặc tệp OpenAPI, một thông tin xác thực hoạt động cho môi trường thử nghiệm và bất kỳ câu hỏi nào mà nhóm hỗ trợ của bạn đã mệt mỏi khi trả lời. Những câu hỏi đó là dàn ý.

Không bao gồm

Bản sao tiếp thị. Điều này tài liệu hóa chính xác những gì phần mềm làm; trang đích là một nghề khác.

Thời gian hoàn thành và giao tiếp

Bản nháp hoàn chỉnh đầu tiên thường đến trong vòng một tuần và bạn xem xét nó dựa trên các câu hỏi mà nhóm hỗ trợ của riêng bạn vẫn đang trả lời. Tôi thà được kỹ sư biết các trường hợp biên sửa lỗi sớm hơn là giao một thứ gì đó bóng bẩy và sai. Mọi ví dụ trong tài liệu cuối cùng đã được thực thi dựa trên API của bạn, vì vậy không có gì trong đó là mong muốn.