Lesson 8.1: OpenAPI & Swagger

Thời lượng: 20 phút
Level: Beginner
Yêu cầu: Đã hiểu về REST API và Response Envelope.

Mục tiêu bài học

Sau bài học này, bạn sẽ:

• Hiểu tiêu chuẩn OpenAPI Specification (OAS).
• Biết cách cấu trúc một file YAML/JSON để mô tả endpoint.
• Sử dụng Swagger UI để hiển thị tài liệu API một cách trực quan.

Nội dung chính

1. OpenAPI Specification (OAS) là gì?

OpenAPI là một tiêu chuẩn quốc tế dùng để mô tả RESTful API. Nó cho phép cả con người và máy tính hiểu rõ khả năng của một service mà không cần đọc mã nguồn.

Lợi ích:

• Single Source of Truth: Code và Docs luôn khớp nhau.
• Auto-generation: Tự động tạo code Client (SDK), Mock server và Test cases.
• Tiêu chuẩn hóa: Mọi lập trình viên trên thế giới đều có thể đọc hiểu.

2. Cấu trúc một file OpenAPI chuẩn

File OpenAPI thường có định dạng YAML và chia làm các phần chính:

• info: Thông tin chung (Tên API, Version, Mô tả).
• servers: Danh sách địa chỉ server (Dev, Staging, Product).
• paths: Danh sách các endpoint và phương thức (GET, POST...).
• components: Định nghĩa các Schema dùng chung (VD: Response Envelope, User Object).

Ví dụ một đoạn YAML:

paths:
  /users/{id}:
    get:
      summary: Lấy thông tin user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

3. Swagger UI: Bộ mặt của API

Swagger UI là công cụ biến file YAML khô khan phía trên thành một trang web đẹp mắt, cho phép:

• Xem danh sách API theo nhóm (Tags).
• Thử nghiệm gọi API trực tiếp (Try it out).
• Xem cấu trúc Request/Response mẫu.

Nguyên tắc then chốt

"Documentation as Code."

Tài liệu không nên là một file Word hay PDF nằm riêng lẻ. Nó nên được sinh ra trực tiếp từ code (sử dụng Decorators/Annotations) hoặc nằm trong cùng Repository với code. Khi bạn sửa một trường trong DB và cập nhật code, tài liệu phải tự động cập nhật theo.

Thực hành

Bài tập 1: Đọc và giải mã file Swagger

Bối cảnh: Đồng nghiệp gửi cho bạn một link Swagger. Bạn nhìn thấy một nút màu đỏ ghi "POST /auth/login".

Yêu cầu:

• Hãy tìm xem trong phần Request Body, API này yêu cầu những trường thông tin nào?
• API này có thể trả về những mã lỗi (Status Code) nào?

Tình huống thực tế

Scenario 1: Onboarding thành viên mới

Bối cảnh: Một bạn Dev Frontend mới gia nhập team. Thay vì dành 4 tiếng để ngồi giải thích từng API cho bạn ấy.

Giải quyết: Bạn chỉ cần gửi một đường link duy nhất: https://api.yourcompany.com/docs. Nhờ có Swagger UI với mô tả đầy đủ và khả năng "Try it out", bạn dev mới có thể tự mày mò và bắt đầu code ngay trong buổi sáng đầu tiên. Đây chính là sức mạnh của Documentation trong việc tăng năng suất team.

Câu hỏi phỏng vấn

Junior/Mid Level

1. Q: "Contract-First" và "Code-First" trong Documentation khác nhau thế nào? A:
   • Contract-First: Bạn viết file YAML OpenAPI trước để thống nhất với team, sau đó mới viết code Backend theo file đó. (Ưu tiên cho team làm việc song song).
   • Code-First: Bạn viết code trước, dùng các thư viện (như swagger-jsdoc hoặc NestJS Swagger) để tự động generate ra file YAML từ code. (Tiện lợi, nhanh chóng, code và docs luôn đồng bộ).

Tóm tắt

Những điều cần nhớ

• OpenAPI là tiêu chuẩn mô tả.
• Swagger là bộ công cụ hiển thị.
• Tài liệu phải luôn đi kèm với code.

Bước tiếp theo

Trong bài tiếp theo, bạn sẽ học về Lesson 8.2: Interactive Docs - Cách biến tài liệu thành một phòng thí nghiệm (Sandbox) cho developer.

Tiếp tục bài 8.2 →