So sánh Swagger UI và Apidog! Kỹ thuật quản lý tài liệu từ góc nhìn thực tế của nhà phát triển API

Gần đây, trong cuộc thảo luận của team về việc quản lý tài liệu RESTful API, chúng tôi đã đề cập đến việc "liệu có nên triển khai Swagger UI không". Thành thật mà nói, lúc đầu tôi đã nghĩ "lại một công cụ tài liệu nữa à...", nhưng sau khi thực sự sử dụng thì nó lại tiện lợi đến bất ngờ! Hôm nay tôi muốn chia sẻ trải nghiệm thực tế của mình với Swagger UI.

Swagger UI là gì? Cảm nhận sau khi trải nghiệm thực tế

Swagger UI là một công cụ UI mã nguồn mở dùng để hiển thị tài liệu Web API. Lần đầu tiếp xúc, tôi đã đánh giá thấp nó với suy nghĩ "chỉ là công cụ hiển thị tài liệu thôi mà?", nhưng thực tế nó lại mạnh mẽ đến bất ngờ.

Khi sử dụng, thông tin về endpoint API, tham số, phản hồi được hiển thị rất rõ ràng. Điều tôi đặc biệt thích là tính năng kiểm thử API ngay tại chỗ! Không cần phải mở Postman, có thể gửi request ngay khi đang xem tài liệu, thật sự rất tiện lợi.

openapi: 3.0.0
info:
  title: API Mẫu
  description: API mẫu cho demo
  version: 1.0.0
servers:
  - url: http://localhost:8080
paths:
  /users:
    get:
      summary: Lấy danh sách người dùng
      description: Lấy danh sách tất cả người dùng
      responses:
        '200':
          description: Danh sách người dùng
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    email:
                      type: string
                      format: email

Chỉ cần chuẩn bị một file YAML như trên, tài liệu dễ đọc sẽ được tự động tạo ra. Được xây dựng bằng HTML, CSS, JavaScript nên cũng có thể tùy chỉnh. Tương thích tuyệt vời với RESTful API, đã trở thành công cụ tiêu chuẩn trong phát triển API.

Thành thật mà nói... Tôi đã gặp phải giới hạn của Swagger UI

Mặc dù Swagger UI rất tiện lợi, nhưng khi sử dụng trong dự án thực tế, tôi thường gặp phải tình huống "Ủa? Cái này không làm được à?". Thành thật mà nói, những điểm sau đây khá khó khăn:

• Chức năng quản lý API còn thiếu: Hiển thị tài liệu và kiểm thử thì được, nhưng khi đến quản lý vòng đời API hay quản lý phiên bản thì lại yếu. Cuối cùng, team chúng tôi phải sử dụng kết hợp với công cụ khác.

• Không phù hợp cho phát triển theo nhóm: Khi nhiều người cùng thiết kế hoặc thay đổi API đồng thời, Swagger UI dựa trên file HTML tĩnh sẽ gặp hạn chế. Tình huống "ai đó đã cập nhật tài liệu nhưng không được chia sẻ" thường xuyên xảy ra.

• Khó khăn khi kết nối với các công cụ khác: Khi nghĩ đến việc tích hợp với CI/CD pipeline hoặc API gateway, Swagger UI đơn lẻ không đủ. Việc phải cập nhật file thủ công cũng rất phiền phức.

Khi đang gặp khó khăn với những hạn chế này, đồng nghiệp đã giới thiệu cho tôi "Thử Apidog xem?". Ban đầu tôi nghĩ "lại một công cụ mới à...", nhưng sau khi thử thì nó lại dễ sử dụng hơn tưởng tượng! Nó giữ lại những ưu điểm của Swagger UI đồng thời giải quyết hầu hết các vấn đề nêu trên.

Thực hành! Từ tạo tài liệu API đến kiểm thử với Swagger UI

Hãy cùng thử sử dụng Swagger UI. Ban đầu việc thiết lập môi trường hơi phức tạp, nhưng một khi đã cài đặt xong thì sau đó rất dễ dàng.

1. Thiết lập môi trường phát triển

Đầu tiên, cài đặt Swagger UI. Bạn có thể clone từ GitHub hoặc sử dụng npm:

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm run dev

Sau đó truy cập http://localhost:3200/ trên trình duyệt, Swagger UI sẽ khởi động. Tuy nhiên, phương pháp này thuận tiện khi cần tùy chỉnh, nếu chỉ muốn hiển thị tài liệu thì phương pháp sau đơn giản hơn.

2. Phương pháp chạy trên Web server đơn giản

Sử dụng module http-server của Node.js để khởi động Swagger UI dễ dàng hơn:

npm install -g http-server

Sau đó, di chuyển đến thư mục chứa file đặc tả Swagger:

cd {your-oas-document-dir}
http-server --cors

Truy cập http://localhost:8080, Swagger UI sẽ khởi động. Sau đó nhập URL của swagger.yaml vào ô nhập liệu phía trên và nhấn nút "Explore", tài liệu API sẽ hiển thị.

Thành thật mà nói, ban đầu tôi đã bối rối với các thiết lập này. Tôi đã nghĩ "tại sao lại cần những bước phức tạp thế này...". Đặc biệt, việc yêu cầu tất cả thành viên trong team cùng thiết lập môi trường giống nhau khá vất vả.

Sử dụng Apidog giải quyết mọi vấn đề của Swagger UI!

Khi đang sử dụng Swagger UI và nghĩ "liệu có cách nào đơn giản hơn không", tôi đã gặp công cụ Apidog. Nó thực sự tiện lợi và hiện tại cả team đang sử dụng.

Điểm tốt của Apidog là không chỉ có thể import trực tiếp file YAML hoặc JSON của Swagger, mà còn cung cấp tích hợp kiểm thử API, tính năng mock, tích hợp CI/CD, quản lý phiên bản. Đặc biệt trong phát triển theo nhóm, khả năng chỉnh sửa cộng tác theo thời gian thực và quản lý lịch sử thay đổi là những lợi thế lớn.

Với Swagger UI, mỗi lần phải khởi động server và cấu hình rất phiền phức, nhưng với Apidog, không cần những công việc phức tạp đó, có thể tập trung ngay vào việc tạo tài liệu API và kiểm thử. Tôi thực sự nghĩ "nếu biết dễ dàng như vậy, lẽ ra nên triển khai sớm hơn".

Tổng kết: Swagger UI từ góc nhìn của nhà phát triển API

Swagger UI chắc chắn là một công cụ xuất sắc, nhưng trong các dự án thực tế, tôi thường cảm thấy giới hạn về chức năng. Đặc biệt khi nghĩ đến phát triển theo nhóm và tích hợp CI/CD, các công cụ tích hợp như Apidog sẽ giúp hiệu quả công việc tăng lên đáng kể.

Cá nhân tôi nghĩ, với dự án nhỏ hoặc tài liệu API đơn giản thì Swagger UI là đủ, nhưng với phát triển API chuyên nghiệp, nên cân nhắc các công cụ tích hợp như Apidog. Sử dụng kết hợp cả hai công cụ sẽ giúp phát triển API hiệu quả hơn.

Cuối cùng, bạn đang sử dụng công cụ quản lý tài liệu API nào? Nếu có kinh nghiệm với Swagger UI hoặc Apidog, hãy chia sẻ trong phần bình luận!

Câu hỏi thường gặp

Sự khác biệt giữa đặc tả Swagger và đặc tả OpenAPI là gì?

Ban đầu tôi cũng bối rối về điều này. Nói đơn giản, đặc tả Swagger là phiên bản gốc, còn đặc tả OpenAPI là phiên bản kế thừa. Đặc tả OpenAPI được mở rộng dựa trên đặc tả Swagger, bao gồm định nghĩa API chi tiết hơn và các tính năng bảo mật. Hiện nay, đặc tả OpenAPI đã trở thành tiêu chuẩn.

Sự khác biệt giữa Swagger và Swagger UI là gì?

Điều này cũng thường bị nhầm lẫn, nhưng Swagger chỉ định dạng thức của tài liệu đặc tả, còn Swagger UI là công cụ hiển thị tài liệu đặc tả đó một cách dễ đọc. Nói cách khác, mối quan hệ là sử dụng Swagger UI để hiển thị tài liệu đặc tả được viết bằng Swagger.

Swagger UI có miễn phí không?

Vâng, hoàn toàn miễn phí! Swagger UI là dự án mã nguồn mở được cấp phép theo Apache License 2.0, nên có thể tự do sử dụng kể cả cho mục đích thương mại. Tuy nhiên, khi sử dụng, bạn cần tự chuẩn bị tài liệu đặc tả API theo định dạng YAML hoặc JSON. Đây có thể là rào cản ban đầu.