Bài 44 — API Documentation: Postman, Swagger/OpenAPI — Chương Trình Chứng Chỉ Business Analyst Hoàn Chỉnh

Mở đầu — vì sao bài này quan trọng

Ở bài trước bạn đã hiểu API là gì, REST hoạt động ra sao, JSON trông thế nào và các status code phổ biến. Nhưng trong công việc thực tế, hiểu API "trong đầu" thôi là chưa đủ. Vấn đề lớn nhất của hầu hết dự án phần mềm không phải là "API không chạy" mà là "không ai hiểu API chạy thế nào". Developer team A xây một endpoint, developer team B tích hợp vào, ba tháng sau có người mới vào và chẳng ai nhớ endpoint đó nhận tham số gì, trả về cái gì khi lỗi. Đó chính là khoảng trống mà API Documentation (tài liệu mô tả API) lấp đầy — và đó cũng là nơi BA tạo ra giá trị rất rõ ràng.

Nhiều bạn BA nghĩ "viết tài liệu API là việc của dev". Sai. Trong các dự án trưởng thành, BA là người đảm bảo rằng tài liệu API phản ánh đúng yêu cầu nghiệp vụ: trường nào bắt buộc, quy tắc validate ra sao, mã lỗi nào tương ứng với tình huống nghiệp vụ nào. BA không cần code ra API, nhưng BA bắt buộc phải đọc thông thạo tài liệu API, review để bắt thiếu sót, và trong nhiều trường hợp phải tự viết hoặc chỉnh sửa một file đặc tả OpenAPI để mô tả đúng điều business cần. Khi bạn ngồi họp với một đối tác tích hợp — ví dụ một ngân hàng muốn kết nối với cổng thanh toán — thứ hai bên đặt lên bàn không phải slide PowerPoint, mà là một file Swagger.

Bài này tập trung vào hai công cụ xương sống của thế giới API documentation: Swagger/OpenAPI (chuẩn để mô tả API) và Postman (công cụ để thử nghiệm, khám phá và làm tài liệu sống cho API). Học xong bài này, bạn đọc được một file OpenAPI, tự gửi được một request trong Postman để kiểm chứng yêu cầu, và biết cách dùng tài liệu API như một artifact giao tiếp trong dự án.

Khái niệm cốt lõi

OpenAPI là gì, Swagger là gì

Hai cái tên này hay bị nhầm. OpenAPI Specification (OAS) là một chuẩn — một bộ quy tắc về cách mô tả một REST API bằng định dạng YAML hoặc JSON, sao cho cả con người và máy đều đọc được. Phiên bản phổ biến hiện nay là OpenAPI 3.0 và 3.1. Swagger là bộ công cụ xoay quanh chuẩn đó: Swagger UI (trang web hiển thị tài liệu đẹp, bấm thử được), Swagger Editor (trình soạn thảo file đặc tả), Swagger Codegen (sinh code từ đặc tả). Nói ngắn gọn: OpenAPI là ngôn ngữ, Swagger là công cụ nói ngôn ngữ đó. Ngày nay nhiều người dùng "Swagger" và "OpenAPI" thay thế nhau, nhưng bạn nên biết sự khác biệt để không bị bắt lỗi khi nói chuyện với kiến trúc sư hệ thống.

Tại sao chuẩn này lại quan trọng đến vậy? Vì nó biến tài liệu API từ một file Word dễ lỗi thời thành một single source of truth (nguồn chân lý duy nhất). Khi đặc tả OpenAPI được cập nhật, Swagger UI tự đổi, code client tự sinh lại, test tự cập nhật. Tài liệu và thực tế không còn lệch nhau.

Cấu trúc một file OpenAPI

Một file OpenAPI gồm các phần chính: openapi (phiên bản chuẩn), info (tên, mô tả, version của API), servers (URL gốc), paths (danh sách endpoint), và components (các thành phần dùng lại như schema dữ liệu, cơ chế bảo mật). Đây là phần quan trọng nhất với BA: paths mô tả từng endpoint làm gì, còn components/schemas mô tả cấu trúc dữ liệu nghiệp vụ.

Hãy xem một ví dụ thực tế — endpoint tra cứu thông tin tài khoản trong một hệ thống ngân hàng:

openapi: 3.0.0
info:
  title: Core Banking API
  description: API tra cứu và quản lý tài khoản khách hàng
  version: 1.2.0
servers:
  - url: https://api.vietcombank-demo.vn/v1
paths:
  /accounts/{id}:
    get:
      summary: Lấy thông tin chi tiết một tài khoản
      parameters:
        - name: id
          in: path
          required: true
          description: Số tài khoản (12 chữ số)
          schema:
            type: string
            pattern: '^[0-9]{12}$'
      responses:
        '200':
          description: Tra cứu thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Không tìm thấy tài khoản
        '403':
          description: Không có quyền truy cập tài khoản này
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: string
          example: "001234567890"
        ownerName:
          type: string
          example: "NGUYEN VAN AN"
        balance:
          type: number
          format: double
          example: 15750000
        currency:
          type: string
          enum: [VND, USD]
        status:
          type: string
          enum: [ACTIVE, FROZEN, CLOSED]
      required:
        - id
        - ownerName
        - balance
        - currency
        - status

Đọc đoạn này như một BA, bạn thấy ngay nhiều thông tin nghiệp vụ: số tài khoản phải đúng 12 chữ số (pattern), trạng thái tài khoản chỉ có 3 giá trị hợp lệ (enum), và đặc biệt là 3 mã trả về khác nhau — 200 thành công, 404 không tồn tại, 403 không có quyền. Chính cái 403 này thường bị developer bỏ sót nếu BA không nhắc: nghiệp vụ ngân hàng yêu cầu phân biệt rõ "tài khoản không tồn tại" với "tài khoản tồn tại nhưng bạn không được phép xem" — vì lý do bảo mật và tuân thủ.

Postman: nơi API trở nên sống động

Nếu OpenAPI là bản vẽ thiết kế thì Postman là phòng thí nghiệm để bạn thật sự bấm nút và xem API phản ứng. Postman là công cụ desktop/web cho phép bạn gửi request HTTP đến một endpoint, nhập tham số, header, body, rồi xem response trả về. Với BA, Postman có ba công dụng cực kỳ thực tế: (1) kiểm chứng yêu cầu — gửi thử request để xác nhận API hành xử đúng như spec; (2) khám phá API của đối tác — khi tích hợp bên thứ ba, bạn tự thử trước khi viết tài liệu; (3) làm tài liệu sống qua Postman Collection — một bộ request mẫu được lưu lại, chia sẻ cho cả team, có kèm ví dụ và mô tả.

Một khái niệm bạn nên nắm là Collection và Environment. Collection là một nhóm các request được tổ chức theo chức năng (ví dụ "Tài khoản", "Chuyển khoản", "Lịch sử giao dịch"). Environment là tập biến số môi trường — ví dụ {{base_url}} trỏ tới server staging hay production, {{token}} chứa mã xác thực — giúp bạn chuyển môi trường mà không phải sửa từng request.

Tình huống thực tế

Tình huống 1 — Ngân hàng số tích hợp eKYC với đối tác

Ngân hàng số Cake (giả định theo bối cảnh thực tế VN) muốn tích hợp dịch vụ xác thực giấy tờ với một nhà cung cấp eKYC bên ngoài là VNPT eKYC. Nhà cung cấp gửi sang một file Swagger mô tả 4 endpoint: upload ảnh CCCD, đối chiếu khuôn mặt, kiểm tra liveness, và trả kết quả định danh. Anh Tuấn, BA của Cake, mở file đó trong Swagger Editor và phát hiện một vấn đề: endpoint đối chiếu khuôn mặt trả về trường matchScore kiểu số từ 0 đến 1, nhưng tài liệu không hề ghi ngưỡng nào được coi là đạt. Phía dev nếu cứ thế code thì sẽ tự đặt ngưỡng tùy ý.

Anh Tuấn dùng Postman gửi thử 20 cặp ảnh test, ghi lại điểm số, rồi ngồi cùng đối tác chốt ngưỡng 0.82 là "đạt", từ 0.70 đến 0.82 là "cần review thủ công", dưới 0.70 là "từ chối". Yêu cầu này được anh viết bổ sung vào phần description của trường matchScore trong file OpenAPI và đưa vào FRD. Bài học: tài liệu API mô tả cấu trúc dữ liệu nhưng thường thiếu quy tắc nghiệp vụ gắn với dữ liệu đó. Đó chính xác là chỗ BA phải nhảy vào, và Postman là công cụ để bạn thu thập bằng chứng thực tế thay vì tranh luận suông.

Tình huống 2 — Sàn thương mại điện tử và bộ sưu tập Postman cho team

Một sàn TMĐT quy mô vừa ở TP.HCM (giả định, kiểu mô hình Tiki thu nhỏ) có 6 team backend, mỗi team làm một mảng: sản phẩm, giỏ hàng, thanh toán, vận chuyển, khuyến mãi, đánh giá. Vấn đề: mỗi khi QA hay BA cần test một luồng đặt hàng, họ phải hỏi từng dev "endpoint này gọi sao". Mỗi lần như vậy mất nửa ngày.

Chị Linh, BA trưởng nhóm, đề xuất chuẩn hóa: mỗi team phải duy trì một Postman Collection cho mảng của mình, kèm ít nhất một ví dụ request thành công và một ví dụ lỗi cho mỗi endpoint, tất cả gộp vào một workspace chung tên "Order Flow E2E". Chị thiết lập một Environment "Staging" với biến {{token}} lấy tự động qua một request đăng nhập đặt ở đầu collection. Sau hai sprint, thời gian onboarding một thành viên mới vào hiểu luồng đặt hàng giảm từ khoảng 3 ngày xuống còn nửa ngày, và số câu hỏi "endpoint này dùng thế nào" trong kênh chat team giảm rõ rệt. Bài học: tài liệu API không phải sản phẩm viết một lần rồi bỏ, nó là tài sản chung cần được tổ chức và bảo trì. BA có thể là người thiết lập "luật chơi" về việc duy trì tài liệu sống, kể cả khi không tự viết từng dòng.

Tình huống 3 — Khi tài liệu nói một đằng, API làm một nẻo

Một công ty fintech cung cấp ví điện tử nhận tài liệu OpenAPI từ một cổng thanh toán đối tác. Tài liệu ghi endpoint hoàn tiền (POST /refunds) trả về status 200 khi thành công. BA tên Hùng test trên Postman thì thấy: khi hoàn tiền thành công, API thực tế trả về 202 Accepted chứ không phải 200, vì việc hoàn tiền là bất đồng bộ — nó được đưa vào hàng đợi xử lý chứ chưa hoàn tất ngay. Nếu dev tin theo tài liệu và chỉ xử lý 200, hệ thống sẽ hiểu nhầm mọi giao dịch hoàn tiền là thất bại.

Hùng chụp lại response 202 trong Postman làm bằng chứng, báo lại đối tác để họ sửa tài liệu, đồng thời ghi chú vào yêu cầu rằng luồng hoàn tiền cần có webhook để nhận kết quả cuối cùng. Bài học: tài liệu API có thể sai hoặc lỗi thời. Đừng bao giờ tin tài liệu một cách mù quáng — luôn kiểm chứng bằng request thật. Status code 202 so với 200 là khác biệt nhỏ trên giấy nhưng là khác biệt sống còn về mặt thiết kế hệ thống.

Hướng dẫn từng bước

Dưới đây là quy trình thực tế để một BA đọc và kiểm chứng một API mới, từ tài liệu đến thực nghiệm.

Bước 1 — Lấy và mở file đặc tả. Yêu cầu dev hoặc đối tác gửi file OpenAPI (đuôi .yaml hoặc .json) hoặc đường link Swagger UI. Mở Swagger UI nếu có — nó hiển thị trực quan từng endpoint, có nút "Try it out".

Bước 2 — Đọc tổng quan trước, chi tiết sau. Xem phần info để biết version API, xem servers để biết môi trường. Lướt danh sách paths để nắm có bao nhiêu endpoint và chúng phục vụ nghiệp vụ gì. Đừng sa vào chi tiết một endpoint ngay.

Bước 3 — Soi từng endpoint theo lăng kính nghiệp vụ. Với mỗi endpoint quan trọng, tự hỏi: tham số nào bắt buộc (required)? Có ràng buộc định dạng nào (pattern, enum, minLength)? Các mã response gồm những gì — đã đủ các tình huống lỗi nghiệp vụ chưa (thiếu quyền, dữ liệu sai, trùng lặp)?

Bước 4 — Tạo request trong Postman. Mở Postman, tạo một Collection mới đặt tên theo API. Tạo một Environment chứa base_url và token. Tạo request đầu tiên: chọn method (GET/POST...), dán URL dùng biến {{base_url}}, thêm header Authorization nếu cần, và với POST thì nhập body JSON.

Bước 5 — Gửi và đối chiếu. Bấm Send, xem status code và body trả về. Đối chiếu với tài liệu: cấu trúc có khớp không, status code có đúng không. Mọi sai lệch — ghi lại làm phát hiện (finding).

Bước 6 — Test các trường hợp biên. Đừng chỉ test "happy path". Gửi request thiếu trường bắt buộc, gửi giá trị sai định dạng, gửi token hết hạn. Xem API phản hồi ra sao và đối chiếu với yêu cầu nghiệp vụ.

Bước 7 — Lưu thành tài liệu sống. Lưu các request đã chạy đúng vào Collection, thêm mô tả ngắn cho mỗi request, kèm ví dụ (Save Response as Example). Chia sẻ Collection cho team. Nếu phát hiện thiếu sót trong spec, bổ sung vào file OpenAPI phần description hoặc đưa vào FRD/SRS.

Lỗi thường gặp & mẹo

Lỗi 1 — Nhầm Swagger với OpenAPI và dùng sai version. Có dự án trộn lẫn cú pháp OpenAPI 2.0 (tên cũ là Swagger 2.0) với 3.0; hai phiên bản này có cấu trúc khác nhau ở phần components và requestBody. Mẹo: luôn kiểm tra dòng openapi: 3.0.0 ở đầu file để biết bạn đang đọc chuẩn nào.

Lỗi 2 — Chỉ đọc happy path. BA mới hay chỉ quan tâm endpoint trả về gì khi thành công, bỏ qua các mã lỗi. Nhưng phần lớn rủi ro nghiệp vụ nằm ở các tình huống lỗi. Mẹo: lập một danh sách kiểm tra "với endpoint này, những tình huống xấu nào có thể xảy ra?" và đối chiếu với danh sách response code trong spec.

Lỗi 3 — Tin tài liệu mà không kiểm chứng. Như tình huống cổng thanh toán ở trên, tài liệu có thể sai. Mẹo: nguyên tắc "trust but verify" — luôn gửi ít nhất một request thật cho mỗi endpoint quan trọng.

Lỗi 4 — Để token và mật khẩu thật trong Collection rồi share. Đây là lỗi bảo mật phổ biến. Mẹo: luôn để thông tin nhạy cảm trong Environment (kiểu biến secret), không hardcode vào request, và không export Environment production khi chia sẻ.

Lỗi 5 — Lẫn lộn giữa path parameter, query parameter và body. Trong /accounts/{id} thì id là path param; còn ?page=2&size=20 là query param; còn dữ liệu gửi khi tạo mới nằm trong body. Mẹo: nhìn vào in: path, in: query trong spec để phân biệt — gửi sai chỗ là API báo lỗi ngay.

Mẹo nâng cao: Postman có tab "Tests" cho phép viết vài dòng kiểm tra tự động (ví dụ kiểm tra status là 200, kiểm tra response có trường balance). BA không cần giỏi code vẫn dùng được những đoạn mẫu này để biến request thành một bài kiểm thử nhỏ, hữu ích khi cần regression nhanh.

Bài tập thực hành

Đọc spec: Lấy đoạn YAML endpoint /accounts/{id} ở phần Khái niệm cốt lõi. Viết ra (bằng tiếng Việt) toàn bộ quy tắc nghiệp vụ bạn suy ra được từ spec đó, và liệt kê ít nhất 2 tình huống lỗi nghiệp vụ mà spec chưa xử lý (gợi ý: nghĩ về tài khoản đã đóng, hoặc số tài khoản nhập sai định dạng).

Viết spec: Tự viết một đoạn OpenAPI 3.0 mô tả endpoint POST /transfers (chuyển khoản) gồm: body có fromAccount, toAccount, amount, note; các trường bắt buộc; ràng buộc amount phải lớn hơn 0; và 3 mã response — 201 tạo lệnh thành công, 400 dữ liệu sai, 422 số dư không đủ.

Thực hành Postman: Dùng một API công khai miễn phí (ví dụ https://reqres.in/api/users hoặc https://jsonplaceholder.typicode.com/posts). Tạo một Collection, một Environment với base_url, gửi một request GET và một request POST, lưu response làm Example, rồi viết mô tả ngắn cho từng request.

Tư duy phản biện: Viết một đoạn 5–7 câu giải thích cho một dev junior tại sao việc trả về 202 thay vì 200 cho luồng hoàn tiền bất đồng bộ lại quan trọng, và webhook giải quyết vấn đề gì trong tình huống đó.

Tóm tắt

API Documentation là cầu nối giữa yêu cầu nghiệp vụ và hệ thống kỹ thuật, và BA là người giữ cho cây cầu đó vững. OpenAPI là chuẩn mô tả REST API bằng YAML/JSON, trong đó phần paths và components/schemas chứa đầy thông tin nghiệp vụ mà BA phải đọc được — trường bắt buộc, ràng buộc dữ liệu, và quan trọng nhất là danh sách các mã response phản ánh các tình huống nghiệp vụ. Swagger là bộ công cụ hiển thị và soạn thảo chuẩn đó. Postman là phòng thí nghiệm để bạn kiểm chứng API bằng request thật, khám phá API đối tác, và xây dựng Collection làm tài liệu sống cho cả team.

Ba thông điệp cốt lõi cần khắc ghi: thứ nhất, tài liệu API mô tả cấu trúc nhưng thường thiếu quy tắc nghiệp vụ — đó là chỗ BA thêm giá trị. Thứ hai, đừng bao giờ tin tài liệu mù quáng, luôn kiểm chứng bằng Postman. Thứ ba, tập trung vào các tình huống lỗi và biên, vì rủi ro nghiệp vụ nằm ở đó chứ không nằm ở happy path. Khi bạn thành thạo việc đọc một file Swagger và mở Postman gửi vài request để kiểm tra một yêu cầu, bạn đã bước qua ranh giới giữa "BA chỉ ngồi họp" và "BA hiểu hệ thống" — một bước tiến lớn trong sự nghiệp phân tích nghiệp vụ.