Postman ngoài việc cung cấp 1 công cụ test API còn hỗ trợ chúng ta làm API document cực kỳ chuyên nghiệp và dễ dàng. API document này có thể dùng chung cho cả team và khách hàng. Thông thường, API thường do Dev viết trên google sheets nhưng đến 1 giai đoạn phát triển nào đó dev sẽ lười viết docs API hoặc API sửa nhiều, họ sẽ không nhớ để update những sửa chữa đấy.
API Document của Postman có điểm ưu việt hơn khi nó update luôn những gì mình thao tác trên khung làm việc vào API docs. Thực ra là cứ mỗi khi ta tạo ra 1 Collection thì Postman đã tạo Document cho Collection đó rồi, nên việc của chúng ta tương đối nhàn hạ. :))))

Muốn biết tài khoản của chúng ta có bao nhiêu Collections. Click chọn [Collection Links]


Toàn bộ Docs API của những Collections sẽ được show ra.

  • Click vào View Docs để xem API Docs ( đây là link của trạng thái Private, link này không share được).
  • Click vào Publish để tạo Link share Public (Link này thì ai cũng nhìn được nội dung). Bạn chỉ cần copy cái link rồi gửi cho người khác.

Vấn đề là 1 API Docs gồm những thành phần gì và thể hiện những phần đấy trong Postman như thế nào?

Các thành phần của 1 API Document:

  • Tên của API Document
  • Mô tả của API Docs
  • Tên của từng API
  • Mô tả của cả API: Mục đích của API, note lại các mục cần lưu ý
  • Params + mô tả của params
  • Sample Request
  • Sample Response

Tên của API Document

Chính là tên của Collection, cách edit đơn giản, xem lại bài 7.

Mô tả của API Docs


Cách Format đoạn Text này dùng Markdown. Bạn có thế xem thử mẫu ở đây http://markdownlivepreview.com/

Tên của từng API & Mô tả của cả API

Tên của API chính ta tên chúng ta đặt cho từng Request. Cách Edit


Chỗ này cũng hỗ trợ Markdown để format nhé, nói chung là chỗ nào điền text thì Postman cũng hỗ trợ Markdown nhé. :)))))

Params + mô tả của params

Các bạn điền vào phần Param hoặc Body giống như điền API vẫn điền trước đây nhưng khi viết API Docs, lưu ý: KHÔNG điền phần Value. Xem hình

Sample Request & Sample Response

Đây là tính năng Example mà Postman cung cấp.


Bạn Add 1 cái Example rồi điền thông tin giống như 1 API thật sự là xong.

Sample Request

Lúc này thì bạn phải điền Value cho từng Param, không được bỏ trống.

Sample Response
Bạn lấy 1 Reposne mẫu theo cái Sample Request phía trên rồi Paste vào là được.

Sau đó, bạn xem lại thành quả của mình ở 1 trong 2 link Public và Private ở phía đầu bài mình đã nói. Nó sẽ có dạng như sau:

Phần bên trái sẽ là List API có trong dự án, click vào từng API để xem chi tiết.