Viết API Document với apidocjs

Về việc viết document nói chung và API document nói riêng

Document là thứ rất quan trọng khi bàn giao một dự án hay cần tham khảo để bảo trì, phát triển dự án đó. Một số bạn dev sẽ nói mình viết code đẹp rồi, cứ vào đọc là hiểu ngay cần gì làm doc và thẳng thừng nói không với doc. Nhưng khi download một source code về, nhận code từ dev khác hay vào maintain một project thì khóc ròng vì không hiểu người ta viết gì cả. Vậy nên:

1. Nếu bạn định code cái gì, hãy dành thời gian ra viết một chút document cho nó
2. Nếu bạn không cập nhật document thì đừng viết nó ra

Với API, dù bạn viết code đẹp thế nào mà không có gì cho client tham khảo ngoài một API mẫu thì khối API bạn viết sẽ sớm trở thành thảm họa với những lỗi kinh điển như: sai kiểu dữ liệu gửi nhận, sai mã lỗi, tốn thời gian support client, mất kiểm soát khi nâng cấp API version... sau đó thì kiểu gì bạn cũng phải ngồi viết document.

Quay lại với chủ đề, đầu tiên hãy tham khảo TwitterAPI, được trình bày rất chuyên nghiệp, rõ ràng và đầy đủ, tuy nhiên mình đã tham khảo các tool tạo document thế này thì hầu hết phải trả phí, nếu có miễn phí thì rất khó dùng. Cho đến khi tìm được cái này: http://apidocjs.com/
alt text

apidocjs giúp bạn tạo ra api document từ các code comment, bạn có thể import toàn bộ source code để nó tự tìm các comment hoặc viết một file toàn các comment để chương trình xuất ra file html. apidocjs là một nodejs module, bạn phải cài nodejs và npm trước, sau đó cài đặt bằng npm:

npm install apidoc -g

Các thức hoạt động

Như hình sau, mình có folder api-document-source có các file chứa code comment làm input cho chương trình.
Folder api-document-output là output của chương trình được generate tự động, bạn không cần đụng tới nó, chỉ cần mở file index.html để xem kết quả.
alt text

Bắt đầu viết doc như sau, tạo một file có đuôi cùng với ngôn ngữ bạn dùng để viết API, trong trường hợp này là .js, viết toàn bộ thông tin về một API theo mẫu thế này:

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

Bạn có thể viết thêm các phương thức POST, PUT, DELETE của cùng một model vào một file, apidocjs sẽ tự động scan tất cả các file chứa code comment có cú pháp như trên. Sau đó gõ lệnh sau để generate ra html:

 apidoc -i api-document-source/ -o api-document-output/

Với param -i, -o đơn giản là input folder, output folder. Sau đó mở file index.html trong folder out put để xem kết quả.
Giao diện đơn giản trình bày tất cả API trong một trang, navigate bằng menu bên trái, toàn bộ chi tiết trình bày ở giữa trang
alt text

Tada! vậy là bạn đã có một api document khá gọn gàng và đẹp mắt, có thể deploy output lên một host để cả team dev cùng tham khảo. apidocjs còn hỗ trợ rất nhiều tính năng và ngôn ngữ khác, bạn có thể tham khảo thêm tại http://apidocjs.com/

Happy documentation :)

Bình luận


White
{{ comment.user.name }}
Bỏ hay Hay
{{comment.like_count}}
Male avatar
{{ comment_error }}
Hủy
   

Hiển thị thử

Chỉnh sửa

White

Finn

1 bài viết.
0 người follow
Kipalog
{{userFollowed ? 'Following' : 'Follow'}}
Bài viết liên quan
White
21 3
Giao diện lập trình ứng dụng, còn gọi là API (Application Programming Interface) là chương trình cho phép người dùng sử dụng các phương thức của mộ...
chuong2v viết hơn 2 năm trước
21 3
White
7 5
Setup hệ thống Api với Nodejs trong 1 nốt nhạc Mục đích bài viết là sẽ giúp setup hệ thống api cơ bản, và cung cấp giao diện admin để thao tác với...
Xaolonist viết 9 tháng trước
7 5
{{like_count}}

kipalog

{{ comment_count }}

bình luận

{{liked ? "Đã kipalog" : "Kipalog"}}


White
{{userFollowed ? 'Following' : 'Follow'}}
1 bài viết.
0 người follow

 Đầu mục bài viết

Vẫn còn nữa! x

Kipalog vẫn còn rất nhiều bài viết hay và chủ đề thú vị chờ bạn khám phá!