OpenAPI / Swagger

1. OpenAPI / Swagger là gì?

OpenAPI và Swagger là những khái niệm thường gặp khi phát triển backend và REST API. Chúng giúp lập trình viên mô tả, tài liệu hóa và kiểm thử API một cách rõ ràng hơn, từ đó thuận tiện cho việc phát triển, bảo trì và phối hợp giữa frontend với backend.

OpenAPI là một đặc tả dùng để mô tả API theo một cấu trúc thống nhất. Thông qua đặc tả này, lập trình viên có thể khai báo các endpoint, phương thức HTTP, tham số đầu vào, dữ liệu trả về, mã trạng thái và cơ chế xác thực của API.

Swagger là tên của một nhóm công cụ hỗ trợ làm việc với OpenAPI. Ví dụ, Swagger UI có thể hiển thị tài liệu API dưới dạng giao diện trực quan, cho phép người dùng xem thông tin từng endpoint và gửi request để kiểm tra trực tiếp.

Có thể hiểu đơn giản rằng OpenAPI là quy chuẩn mô tả API, còn Swagger là bộ công cụ hỗ trợ tạo, hiển thị và làm việc với tài liệu API.

2. Mục đích sử dụng OpenAPI / Swagger

OpenAPI và Swagger được sử dụng để giúp việc phát triển và sử dụng API trở nên dễ dàng hơn, đặc biệt trong những dự án có nhiều chức năng hoặc nhiều thành viên cùng tham gia.

Một số mục đích chính gồm:

• Tài liệu hóa API: Mô tả các endpoint, phương thức HTTP, tham số và dữ liệu trả về.
• Hỗ trợ frontend và backend phối hợp: Frontend có thể dựa vào tài liệu để biết cách gửi request và xử lý response mà không cần đọc toàn bộ mã nguồn backend.
• Kiểm thử API: Swagger UI cho phép nhập dữ liệu và gửi request trực tiếp để kiểm tra kết quả.
• Thống nhất cấu trúc dữ liệu: Mô tả các trường dữ liệu trong request và response để các thành viên hiểu và sử dụng thống nhất.
• Hỗ trợ tự động hóa: Tài liệu OpenAPI có thể được sử dụng để tạo mã client, sinh tài liệu hoặc hỗ trợ kiểm thử tự động bằng các công cụ tương thích.

Ví dụ, khi xây dựng API đăng nhập, tài liệu có thể ghi rõ endpoint là /login, phương thức là POST, dữ liệu đầu vào gồm email và password, còn kết quả trả về có thể chứa thông tin người dùng và token xác thực. Nhờ vậy, frontend có thể tích hợp API dễ dàng hơn.

3. Các thành phần thường có trong OpenAPI

Một tài liệu OpenAPI thường mô tả nhiều thông tin liên quan đến cách sử dụng API.

• Paths: Danh sách các đường dẫn API, chẳng hạn /users hoặc /products.
• HTTP Methods: Các phương thức như GET, POST, PUT, PATCH và DELETE.
• Parameters: Những tham số được truyền qua URL, query string hoặc header.
• Request Body: Dữ liệu client gửi lên server, thường sử dụng JSON.
• Responses: Các kết quả server có thể trả về cùng HTTP status code tương ứng.
• Schemas: Mô tả cấu trúc dữ liệu, bao gồm tên trường, kiểu dữ liệu và những trường bắt buộc.
• Security: Mô tả cơ chế bảo vệ API, chẳng hạn sử dụng Bearer Token.

Ví dụ, API lấy thông tin người dùng có thể được mô tả bằng đường dẫn /users/{id}, phương thức GET và tham số id dùng để xác định người dùng cần truy vấn. Tài liệu cũng có thể ghi rõ API trả về mã 200 khi thành công và mã 404 khi không tìm thấy người dùng.

Những thông tin này giúp người sử dụng hiểu cách gọi API mà không cần phải tìm hiểu toàn bộ cách triển khai bên trong server.

4. Swagger UI là gì?

Swagger UI là công cụ hiển thị tài liệu OpenAPI dưới dạng giao diện web trực quan. Thay vì đọc một tệp đặc tả dài, lập trình viên có thể mở Swagger UI để xem danh sách endpoint, phương thức HTTP, tham số đầu vào và cấu trúc response.

Thông thường, mỗi endpoint sẽ có phần mô tả riêng. Người dùng có thể mở endpoint, nhập dữ liệu cần thiết rồi sử dụng chức năng Try it out để gửi request đến server và xem kết quả trả về.

Ví dụ, với API GET /users, người dùng có thể gửi request trực tiếp trên giao diện Swagger UI để kiểm tra danh sách người dùng mà không nhất thiết phải viết frontend riêng hoặc nhập request thủ công bằng một công cụ khác.

Swagger UI đặc biệt hữu ích trong quá trình phát triển và kiểm thử API. Tuy nhiên, việc có giao diện Swagger không đồng nghĩa API đã hoạt động đúng hoặc an toàn. Kết quả vẫn cần được kiểm tra và đối chiếu với yêu cầu của hệ thống.

5. Ví dụ về tài liệu OpenAPI

Tài liệu OpenAPI thường được viết dưới dạng YAML hoặc JSON. Ví dụ dưới đây mô tả một API đơn giản dùng để lấy danh sách người dùng.

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: Get user list
      responses:
        '200':
          description: Request successful

Trong ví dụ này:

• openapi khai báo phiên bản đặc tả OpenAPI.
• info chứa thông tin chung về API, gồm tên và phiên bản tài liệu.
• paths khai báo những đường dẫn API.
• /users là endpoint lấy danh sách người dùng.
• get cho biết endpoint sử dụng phương thức HTTP GET.
• summary mô tả ngắn chức năng của endpoint.
• responses khai báo các kết quả API có thể trả về; trong ví dụ này, mã 200 biểu thị request thành công.

Đây chỉ là ví dụ rút gọn để minh họa cách mô tả API. Trong dự án thực tế, tài liệu thường cần bổ sung cấu trúc dữ liệu trả về, tham số, các trường hợp lỗi và thông tin xác thực nếu có.

6. Sự khác nhau giữa OpenAPI và Swagger

Mặc dù thường được nhắc đến cùng nhau, OpenAPI và Swagger không hoàn toàn giống nhau.

OpenAPI là đặc tả mô tả cách một API hoạt động từ góc độ sử dụng. Nó xác định cấu trúc tài liệu và những thông tin có thể khai báo về endpoint, request, response và bảo mật.

Swagger là tên của bộ công cụ hỗ trợ làm việc với đặc tả này. Một số công cụ phổ biến gồm Swagger UI để hiển thị tài liệu, Swagger Editor để viết và kiểm tra tài liệu, cùng Swagger Codegen để hỗ trợ tạo mã từ đặc tả.

Có thể hình dung OpenAPI giống như bản mô tả thống nhất của một API, còn Swagger cung cấp những công cụ giúp lập trình viên đọc, chỉnh sửa và sử dụng bản mô tả đó thuận tiện hơn.

7. Ứng dụng OpenAPI / Swagger trong dự án thực tế

Trong một dự án backend, OpenAPI và Swagger thường được sử dụng để quản lý tài liệu API trong suốt quá trình phát triển.

Khi backend tạo thêm endpoint mới, tài liệu API cần được cập nhật để phản ánh đúng phương thức HTTP, tham số, dữ liệu đầu vào và response. Frontend có thể dựa vào tài liệu này để tích hợp chức năng, trong khi tester sử dụng Swagger UI để kiểm tra các trường hợp thành công và thất bại.

Đối với những dự án sử dụng Go và Gin-Gonic, lập trình viên có thể dùng các thư viện hỗ trợ tạo tài liệu OpenAPI từ mã nguồn hoặc viết đặc tả OpenAPI riêng. Sau đó, tài liệu có thể được hiển thị bằng Swagger UI để các thành viên cùng sử dụng.

Tuy nhiên, cần bảo đảm tài liệu luôn đồng bộ với API thực tế. Nếu backend đã thay đổi cấu trúc response nhưng tài liệu chưa được cập nhật, frontend có thể tích hợp sai hoặc gặp lỗi khi xử lý dữ liệu.

Ngoài ra, với những API nội bộ hoặc có thông tin nhạy cảm, cần cân nhắc quyền truy cập vào trang tài liệu và không để lộ thông tin bí mật trong phần mô tả API.

8. Kết luận

OpenAPI và Swagger là những công cụ, tiêu chuẩn quan trọng trong quá trình phát triển REST API. OpenAPI cung cấp cách mô tả API theo cấu trúc thống nhất, còn Swagger hỗ trợ hiển thị, chỉnh sửa và khai thác tài liệu đó.

Qua quá trình tìm hiểu, mình hiểu rằng OpenAPI và Swagger không trực tiếp thay thế backend hay tự động bảo đảm API hoạt động chính xác. Giá trị chính của chúng là giúp API có tài liệu rõ ràng, hỗ trợ frontend và backend phối hợp tốt hơn, đồng thời thuận tiện cho việc kiểm thử và bảo trì hệ thống.

Hoàng Minh

Xem tất cả bài viết của tác giả

Bài viết khác

Language Switching trong Flutter

        Trong quá trình phát triển ứng dụng di động, khả năng hỗ trợ nhiều ngôn ngữ ngày càng trở nên quan trọng. Một ứng dụng chỉ sử dụng duy nhất một ngôn ngữ có thể gặp khó khăn khi tiếp cận người dùng ở các quốc gia và khu vực khác […]

Đọc thêm

UTC & Local Time Conversion

Trong thời đại toàn cầu hóa, con người thường xuyên làm việc, học tập và giao tiếp với những người ở các quốc gia khác nhau. Một cuộc họp trực tuyến có thể được tổ chức tại Việt Nam, nhưng người tham gia lại đang ở Hoa Kỳ, Anh, Nhật Bản hoặc Australia. Vì vậy, […]

Đọc thêm

Logging / Monitoring / CI/CD

1. Logging / Monitoring / CI/CD là gì? Trong quá trình phát triển phần mềm, việc viết code để ứng dụng chạy được chỉ là một phần của công việc. Khi đưa ứng dụng vào sử dụng thực tế, lập trình viên còn phải quan tâm đến nhiều vấn đề khác như ứng dụng có […]

Đọc thêm

Docker

1. Docker là gì? Docker là một nền tảng được sử dụng để đóng gói, triển khai và chạy ứng dụng trong các môi trường độc lập, được gọi là Container. Docker giúp lập trình viên đưa mã nguồn, thư viện, các gói phụ thuộc và những thành phần cần thiết để chạy ứng dụng […]

Đọc thêm

Unit Testing và Integration Testing

1. Unit Testing và Integration Testing là gì? Unit Testing và Integration Testing là hai phương pháp kiểm thử phần mềm thường được sử dụng trong quá trình phát triển ứng dụng. Mục đích của hai phương pháp này là kiểm tra xem chương trình có hoạt động đúng theo yêu cầu hay không, đồng […]

Đọc thêm

Message Broker

1. Message Broker là gì? Message Broker là một thành phần trung gian được sử dụng để tiếp nhận, quản lý và chuyển tiếp thông điệp giữa các ứng dụng hoặc các thành phần trong một hệ thống phần mềm. Công nghệ này thường xuất hiện trong những hệ thống Backend, kiến trúc Microservices và […]

Đọc thêm