Login

OpenAPI và Swagger: viết tài liệu API một lần, dùng nhiều nơi

  • author-image

    Nguyễn Đình Cường

  • blog-tag
  • blog-comment 0 comment
  • created-date 09 Nov, 2026
blog-thumbnail

Tài liệu API viết tay trong file Word hay wiki thường lỗi thời chỉ sau vài tuần. OpenAPI cho bạn mô tả API bằng một file có cấu trúc, từ đó sinh được trang tài liệu tương tác, thư viện client, thậm chí test tự động. Viết một lần, dùng ở nhiều nơi.

OpenAPI và Swagger khác nhau thế nào?

OpenAPI là đặc tả (chuẩn mô tả) cho REST API. Swagger là bộ công cụ ban đầu sinh ra cùng đặc tả này, nay vẫn được dùng làm tên gọi cho các công cụ như Swagger UI (trang tài liệu tương tác) và Swagger Editor. Nói gọn: OpenAPI là chuẩn, Swagger là bộ công cụ quanh chuẩn đó.

Một file mô tả API

openapi: 3.0.3info:  title: Thư viện sách  version: 1.0.0paths:  /books:    get:      summary: Lấy danh sách sách      parameters:        - name: page          in: query          schema: { type: integer, default: 1 }      responses:        '200':          description: Thành công          content:            application/json:              schema:                type: array                items: { $ref: '#/components/schemas/Book' }    post:      summary: Thêm sách mới      requestBody:        required: true        content:          application/json:            schema: { $ref: '#/components/schemas/BookInput' }      responses:        '201': { description: Đã tạo }        '422': { description: Dữ liệu không hợp lệ }components:  schemas:    Book:      type: object      properties:        id: { type: integer }        title: { type: string }    BookInput:      type: object      required: [title]      properties:        title: { type: string, minLength: 1 }

Phần components chứa các schema dùng lại, tham chiếu bằng $ref để tránh lặp. Đây là yếu tố giữ file gọn khi API lớn dần.

Hai cách làm việc

  • Design-first (viết đặc tả trước): nhóm cùng thống nhất file OpenAPI, sau đó backend và frontend làm song song, frontend có thể dùng server giả (mock) sinh từ đặc tả.
  • Code-first: viết code trước, rồi dùng chú thích hoặc thư viện để sinh đặc tả. Rất tiện với các framework như FastAPI (sinh tự động), NestJS (module Swagger), Spring (springdoc), Laravel (một số gói bên thứ ba).

Design-first giúp trao đổi sớm trước khi viết code; code-first giúp tài liệu luôn khớp với thực tế. Chọn theo thói quen đội ngũ.

Những gì bạn nhận được

  • Swagger UI hoặc Redoc: trang tài liệu có nút "Try it out" để gọi thử API ngay trên trình duyệt.
  • Sinh client SDK: công cụ như OpenAPI Generator tạo thư viện gọi API cho nhiều ngôn ngữ.
  • Sinh khung server: tạo bộ khung controller từ đặc tả.
  • Kiểm thử hợp đồng: kiểm tra phản hồi thật có khớp mô tả không.
  • Import vào công cụ như Postman: tạo sẵn bộ request mẫu.

Viết đặc tả tốt

  1. Mô tả đủ các phản hồi lỗi (400, 401, 404, 422...) chứ không chỉ trường hợp thành công.
  2. Thêm ví dụ (example) cho tham số và phản hồi, vì ví dụ giúp người đọc hiểu nhanh hơn mọi đoạn văn.
  3. Đánh dấu rõ trường bắt buộc và kiểu dữ liệu, ràng buộc như độ dài hay giá trị lớn nhất.
  4. Khai báo cách xác thực trong securitySchemes (Bearer token, API key, OAuth2).
  5. Gắn thẻ (tags) để nhóm endpoint theo chức năng.

Đưa vào quy trình làm việc

Hãy lưu file đặc tả trong Git cùng mã nguồn và kiểm tra tính hợp lệ của nó trong CI bằng các công cụ lint. Khi ai đó đổi API, người review thấy thay đổi đặc tả ngay trong pull request, nhờ đó thay đổi phá vỡ tương thích được phát hiện sớm. Một số công cụ còn so sánh hai phiên bản đặc tả để báo cáo thay đổi gây hỏng.

Những hiểu lầm hay gặp

Nhiều người nghĩ OpenAPI chỉ là việc "làm cho đẹp trang tài liệu". Thực ra giá trị lớn nhất nằm ở hợp đồng: khi đặc tả là nguồn sự thật, nhóm giao diện, nhóm di động và nhóm kiểm thử đều dựa vào cùng một văn bản. Một hiểu lầm khác là phải viết toàn bộ bằng tay. Với code-first, phần lớn đặc tả được sinh tự động, bạn chỉ bổ sung mô tả và ví dụ. Điều cần cảnh giác là đặc tả sinh tự động nhưng mô tả sơ sài vẫn cho tài liệu kém giá trị, nên hãy dành thời gian viết mô tả rõ ràng cho từng tham số và mã lỗi.

Lời khuyên cuối

Hãy luôn kiểm tra lại bằng thực hành thay vì chỉ đọc lý thuyết: dựng một dự án nhỏ, cố tình tạo lỗi, quan sát log và công cụ gỡ lỗi, rồi sửa. Hãy thử import file đặc tả vào một công cụ gọi API để tạo sẵn bộ request, bạn sẽ thấy ngay giá trị của việc mô tả API có cấu trúc.

Kết luận

OpenAPI biến tài liệu thành tài sản có thể máy đọc được. Dù bạn chọn thiết kế trước hay sinh từ code, hãy đảm bảo đặc tả luôn đồng bộ với API thật. Bước đầu đơn giản: thử viết đặc tả cho hai endpoint của bạn rồi mở bằng Swagger UI và xem tài liệu tự hiện ra.

Nếu muốn luyện tập cùng bài tập thực tế, hãy ghé các khóa học tại codebem.com khi bạn sẵn sàng.

author_photo
Nguyễn Đình Cường

0 comment