API documentation: đọc OpenAPI/Swagger — API and Technical Fundamentals cho BA

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

Hãy tưởng tượng bạn là BA trong một dự án tích hợp giữa sản phẩm của công ty bạn với cổng thanh toán VNPay. Đối tác gửi cho bạn một file tên vnpay-api.yaml dài hơn 1.500 dòng và nói: "Anh chị đọc spec này rồi cho team em biết cần tích hợp những endpoint nào nhé." Nếu bạn không biết đọc OpenAPI, bạn sẽ phải đợi developer dịch lại, mất vài ngày qua lại email, và rủi ro hiểu sai yêu cầu là rất cao.

Đây chính là tình huống mà mọi BA làm việc với API đều gặp. Tài liệu API ngày nay gần như luôn được viết theo chuẩn OpenAPI (tên cũ là Swagger). Đây là "bản vẽ kỹ thuật" của một REST API: nó mô tả API có những endpoint nào, mỗi endpoint nhận tham số gì, trả về dữ liệu ra sao, lỗi nào có thể xảy ra. Biết đọc nó là một trong những kỹ năng tạo khác biệt lớn nhất giữa một BA "biết về API" và một BA "thật sự làm việc được với API".

Trong bài này, mục tiêu của chúng ta rất cụ thể: bạn sẽ biết OpenAPI/Swagger là gì, hiểu cấu trúc một file OpenAPI gồm những phần nào, và quan trọng nhất là đọc được spec để rút ra thông tin nghiệp vụ — chứ không phải để code. BA không cần viết spec từ con số 0 (dù càng giỏi càng tốt), nhưng BA bắt buộc phải đọc hiểu được spec mà developer hoặc đối tác cung cấp.

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

OpenAPI là gì?

OpenAPI Specification (OAS) là một định dạng chuẩn, dễ đọc cho cả người và máy, dùng để mô tả REST API. File OpenAPI được viết bằng YAML hoặc JSON. Nó nói cho bạn biết toàn bộ "hợp đồng" (contract) của API: gọi đến đâu, gửi gì, nhận lại gì — mà không cần đọc một dòng code backend nào.

Một điểm hay gây nhầm lẫn về tên gọi: trước đây chuẩn này tên là Swagger. Năm 2015, công ty SmartBear hiến tặng đặc tả Swagger cho Linux Foundation và nó được đổi tên thành OpenAPI. Vì vậy:

Swagger 2.0 = OpenAPI 2.0 (cùng một thứ, chỉ khác tên).
Từ OpenAPI 3.0 trở đi (3.0, 3.1), tên chính thức là OpenAPI. Đây là phiên bản hiện đại bạn sẽ gặp nhiều nhất.
Chữ "Swagger" giờ chủ yếu chỉ các công cụ quanh chuẩn này: Swagger UI (trang web hiển thị tài liệu API đẹp mắt, bấm thử được), Swagger Editor (trình soạn thảo spec), Swagger Codegen (sinh code từ spec).

Nói ngắn gọn: OpenAPI là chuẩn, Swagger là tên cũ của chuẩn đó và là tên bộ công cụ phổ biến nhất quanh nó.

Cấu trúc một file OpenAPI

Một file OpenAPI 3.0 thường có các khối lớn sau. Bạn không cần nhớ thuộc lòng cú pháp, chỉ cần nhận ra mỗi khối "nói về cái gì".

1. openapi và info — phần đầu, khai báo phiên bản chuẩn và thông tin chung về API.

openapi: 3.0.3
info:
  title: API Quản lý Đơn hàng
  version: 1.2.0
  description: API cho phép tạo, tra cứu và hủy đơn hàng

Với BA, version rất quan trọng: nó cho biết bạn đang đọc spec của phiên bản nào, tránh nhầm với phiên bản cũ.

2. servers — địa chỉ gốc (base URL) để gọi API. Thường có cả môi trường test (sandbox) và production.

servers:
  - url: https://sandbox.api.example.vn/v1
    description: Môi trường thử nghiệm
  - url: https://api.example.vn/v1
    description: Môi trường thật

3. paths — đây là phần "trái tim" của spec, nơi BA dành nhiều thời gian nhất. Mỗi path là một endpoint (ví dụ /orders), bên dưới là các HTTP method (get, post, put, delete) áp dụng cho endpoint đó.

paths:
  /orders:
    post:
      summary: Tạo đơn hàng mới
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Tạo đơn thành công
        '400':
          description: Dữ liệu không hợp lệ

Đọc khối này, một BA rút ra ngay: "Để tạo đơn hàng, ta gọi POST tới /orders, gửi một body JSON kiểu OrderRequest. Nếu thành công trả về mã 201, nếu dữ liệu sai trả về 400."

4. components — kho dùng chung. Phần quan trọng nhất ở đây là schemas — định nghĩa cấu trúc các đối tượng dữ liệu (ví dụ đơn hàng gồm những trường nào, kiểu gì, bắt buộc hay không). $ref bạn thấy ở trên chính là cách "tham chiếu" tới một schema trong components để khỏi viết lặp lại.

components:
  schemas:
    OrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: string
          description: Mã khách hàng
        items:
          type: array
        note:
          type: string
          maxLength: 200

5. securitySchemes (nằm trong components) — mô tả cách xác thực: API Key, Bearer token, OAuth2... BA cần để ý phần này để biết tích hợp cần loại "chìa khóa" nào.

Cách BA nên đọc một spec

Đừng đọc từ trên xuống dưới như đọc tiểu thuyết. Hãy đọc theo góc nhìn nghiệp vụ: với mỗi nghiệp vụ bạn quan tâm (ví dụ "tạo đơn", "hủy đơn"), tìm endpoint tương ứng trong paths, rồi lần theo $ref để xem dữ liệu vào/ra. Mỗi trường dữ liệu trong schema thường là một business rule ẩn: required nghĩa là bắt buộc nhập, maxLength: 200 nghĩa là ghi chú tối đa 200 ký tự, enum liệt kê các giá trị hợp lệ. Đây chính là "mỏ vàng" thông tin cho việc viết user story và acceptance criteria.

Tình huống thực tế

Tình huống 1: BA fintech đọc spec VNPay để ước lượng phạm vi

Lan là BA tại một startup ví điện tử ở TP.HCM. Sếp giao: "Tuần sau họp với VNPay, em đọc trước spec để biết mình cần tích hợp bao nhiêu endpoint." Lan mở Swagger UI mà VNPay cung cấp, vào phần paths và đếm được 4 endpoint liên quan: POST /payment/create (tạo giao dịch), GET /payment/{txnId} (tra cứu trạng thái), POST /payment/refund (hoàn tiền), và một webhook callback.

Khi mở schema của POST /payment/create, Lan thấy trường amount có chú thích minimum: 1000 và currency là enum: [VND]. Cô lập tức ghi nhận hai rule: giao dịch tối thiểu 1.000đ và chỉ hỗ trợ VND. Ở phần securitySchemes, cô thấy yêu cầu một chữ ký HMAC trên mỗi request — nghĩa là đội kỹ thuật sẽ cần xử lý ký số.

Bài học: Chỉ trong một buổi sáng, nhờ đọc spec, Lan ước lượng được phạm vi (4 luồng tích hợp), phát hiện sớm ràng buộc nghiệp vụ (min/currency) và một hạng mục kỹ thuật rủi ro (ký HMAC). Cô bước vào cuộc họp với câu hỏi đúng trọng tâm thay vì ngồi nghe và gật đầu.

Tình huống 2: Sai lệch giữa spec và thực tế tại một sàn TMĐT

Tại một sàn thương mại điện tử ở Hà Nội, BA tên Đức nhận spec OpenAPI cho API tồn kho từ đội backend. Spec ghi endpoint GET /products/{sku}/stock trả về trường quantity kiểu integer. Đức dựa vào đó viết acceptance criteria cho màn hình hiển thị tồn kho.

Khi QA test, họ phát hiện API thực tế còn trả thêm trường reservedQuantity (số lượng đang bị giữ chỗ trong giỏ hàng) mà spec không mô tả. Hóa ра developer đã cập nhật code nhưng quên cập nhật spec — một lỗi cực phổ biến gọi là "spec drift" (spec lệch khỏi thực tế). Vì Đức không biết về reservedQuantity, màn hình hiển thị "còn hàng" trong khi thực tế đã hết do bị giữ chỗ, gây oversell.

Bài học: Spec là hợp đồng, nhưng nó chỉ đáng tin khi được cập nhật. BA giỏi luôn đối chiếu spec với response thật (gọi thử qua Swagger UI hoặc Postman) trước khi chốt yêu cầu, và yêu cầu đội kỹ thuật giữ spec đồng bộ với code.

Tình huống 3: Dùng Swagger UI để onboard đối tác nhanh hơn

Một công ty logistics ở Đông Nam Á cung cấp API tra cứu vận đơn cho hàng trăm shop bán hàng. Trước đây họ gửi file Word mô tả API; mỗi shop tích hợp mất trung bình 3 tuần và liên tục hỏi support. Sau khi chuyển sang xuất bản tài liệu bằng Swagger UI (trang web tương tác sinh tự động từ file OpenAPI), đối tác có thể xem mọi endpoint, đọc schema, và bấm "Try it out" để gọi thử ngay trên trình duyệt với môi trường sandbox.

Kết quả: thời gian tích hợp trung bình giảm xuống còn khoảng 1 tuần, số ticket hỏi support về định dạng dữ liệu giảm rõ rệt. BA của bên logistics đóng vai trò chủ chốt: họ rà soát từng description, bổ sung ví dụ (example) cho mỗi trường để đối tác hiểu ngay.

Bài học: Một spec tốt không chỉ là cú pháp đúng — nó cần description và example rõ ràng. Đây là phần BA đóng góp giá trị nhiều nhất, vì BA hiểu nghiệp vụ và ngôn ngữ của người dùng cuối hơn developer.

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

Đây là quy trình thực tế để bạn đọc một file OpenAPI lần đầu mà không bị "ngợp":

Bước 1 — Mở spec bằng công cụ trực quan. Đừng đọc YAML thô. Dán nội dung file vào [editor.swagger.io](https://editor.swagger.io) hoặc mở qua Swagger UI nếu đối tác đã host sẵn. Công cụ sẽ hiển thị API dưới dạng danh sách endpoint gọn gàng, gập/mở được.

Bước 2 — Đọc phần info và servers trước. Xác nhận bạn đang đọc đúng API, đúng version, và biết có những môi trường nào (sandbox/production). Ghi lại base URL.

Bước 3 — Quét nhanh danh sách paths. Đọc cột summary của từng endpoint để có bản đồ tổng thể: API này làm được những nghiệp vụ gì? Lập một bảng đơn giản: nghiệp vụ — method — path.

Bước 4 — Đi sâu vào từng endpoint bạn quan tâm. Với mỗi endpoint, đọc ba thứ: (a) tham số đầu vào — path params, query params, request body; (b) các response và status code; (c) lần theo $ref để xem schema chi tiết.

Bước 5 — Trích xuất business rules từ schema. Với mỗi trường: required (bắt buộc?), kiểu dữ liệu, enum (giá trị cho phép), minimum/maximum/maxLength (ràng buộc), description (ý nghĩa nghiệp vụ). Đây là nguyên liệu để viết acceptance criteria.

Bước 6 — Kiểm tra securitySchemes. Tích hợp cần loại xác thực nào? API Key, Bearer, OAuth? Điều này ảnh hưởng tới luồng nghiệp vụ và ước lượng công sức.

Bước 7 — Gọi thử nếu có sandbox. Bấm "Try it out" trong Swagger UI để xem response thật, đối chiếu với những gì spec mô tả. Đây là bước phát hiện "spec drift".

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

Lỗi 1: Nhầm Swagger là một thứ khác với OpenAPI. Như đã nói, Swagger 2.0 chính là OpenAPI 2.0. Khi ai đó nói "gửi anh file Swagger", họ đang nói file OpenAPI. Đừng để tên gọi làm bạn bối rối.

Lỗi 2: Tin spec 100% mà không gọi thử. Spec có thể lỗi thời (spec drift). Luôn đối chiếu với môi trường sandbox khi có thể, đặc biệt với những trường quan trọng về nghiệp vụ.

Lỗi 3: Bỏ qua $ref. Nhiều BA đọc đến $ref: '#/components/schemas/OrderRequest' thì dừng lại vì thấy "khó hiểu". Thực ra $ref chỉ là một con trỏ — hãy lần theo nó tới phần components/schemas để thấy định nghĩa đầy đủ. Bỏ qua $ref là bỏ qua phần lớn business rules.

Lỗi 4: Chỉ đọc response thành công, quên các response lỗi. Phần responses với mã 4xx, 5xx mô tả các tình huống lỗi — đây chính là các luồng nghiệp vụ thay thế (alternate flows) mà BA phải viết acceptance criteria cho chúng (ví dụ: khi mã 409 "đơn đã tồn tại" thì màn hình hiển thị gì?).

Mẹo 1: Khi nhận spec, việc đầu tiên hãy hỏi: "Đây là version mấy, được cập nhật lần cuối khi nào, và có sandbox để test không?"

Mẹo 2: Dùng tính năng tìm kiếm (Ctrl+F) trong Swagger Editor để nhảy nhanh tới một trường hoặc endpoint cụ thể trong spec dài hàng nghìn dòng.

Mẹo 3: Khi review spec do đội kỹ thuật viết, BA nên tập trung vào ba thứ trong tầm chuyên môn của mình: description đã rõ nghĩa nghiệp vụ chưa, example đã có chưa, và các ràng buộc (required, enum, min/max) có khớp với business rule thực tế không.

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

Đọc spec mẫu: Truy cập [editor.swagger.io](https://editor.swagger.io). Trang này mặc định mở một spec mẫu (Swagger Petstore). Hãy trả lời: API này có bao nhiêu endpoint? Để "thêm một con thú cưng mới" thì dùng method và path nào? Trường nào trong schema Pet là bắt buộc?

Trích xuất business rules: Chọn một endpoint POST bất kỳ trong spec mẫu, lần theo $ref của request body, và liệt kê ít nhất 5 business rule mà bạn rút ra được từ schema (trường bắt buộc, kiểu dữ liệu, giá trị enum, ràng buộc độ dài...).

Viết acceptance criteria: Từ các business rule ở bài 2, viết 3 acceptance criteria theo định dạng Given-When-Then cho một màn hình nhập liệu tương ứng.

Săn lỗi spec drift: Tìm một API công khai có Swagger UI (ví dụ API của một dịch vụ bạn hay dùng), bấm "Try it out" gọi một endpoint GET đơn giản, và đối chiếu response thật với schema mô tả trong spec. Có trường nào trong response không xuất hiện trong spec không?

Tóm tắt

OpenAPI (tên cũ Swagger) là chuẩn mô tả REST API bằng YAML/JSON — bản vẽ kỹ thuật cho biết API có endpoint nào, nhận gì, trả gì. Swagger 2.0 chính là OpenAPI 2.0; phiên bản hiện đại là OpenAPI 3.0/3.1. Một file OpenAPI gồm các khối chính: info (thông tin chung), servers (base URL), paths (các endpoint — phần quan trọng nhất với BA), và components/schemas (định nghĩa dữ liệu, được tham chiếu qua $ref).

Với BA, kỹ năng cốt lõi không phải viết spec mà là đọc spec để rút ra business rules: mỗi required, enum, min/max trong schema là một quy tắc nghiệp vụ; mỗi response lỗi là một luồng thay thế cần acceptance criteria. Hãy đọc spec theo góc nhìn nghiệp vụ, luôn lần theo $ref, đừng bỏ qua response lỗi, và quan trọng nhất — đối chiếu spec với sandbox thật để tránh "spec drift". Nắm vững kỹ năng này, bạn sẽ tự tin bước vào mọi cuộc họp tích hợp API mà không cần đợi developer "dịch" lại tài liệu.