Thiết lập Swagger UI cục bộ chỉ trong 5 phút - Hướng dẫn cho phát triển API an toàn

Giá trị thực sự của việc sử dụng Swagger UI cục bộ: Chia sẻ từ người đã trải nghiệm

"Chỉ còn 2 ngày nữa là đến hạn, nhưng khách hàng lại yêu cầu thay đổi đặc tả API..."

Tôi đã gặp phải tình huống này trong giai đoạn cuối của một dự án tài chính. Tệ hơn nữa, tôi đang ở khách sạn trong chuyến công tác với kết nối internet không ổn định. Không thể sử dụng các công cụ tài liệu API trực tuyến, tôi đã rơi vào tình trạng bế tắc cho đến khi nhớ ra cách sử dụng Swagger UI cục bộ.

Kết quả là, sử dụng Swagger UI cục bộ đã giúp tôi giải quyết ngay lập tức 3 vấn đề sau:

Có thể tạo và chỉnh sửa tài liệu API đầy đủ ngay cả trong môi trường offline
Phản ánh các thay đổi đặc tả theo thời gian thực ngay cả trong cuộc họp với khách hàng
Có thể sử dụng an toàn trong các dự án có yêu cầu bảo mật nghiêm ngặt

Trong bài viết này, dựa trên kinh nghiệm thực tế của mình, tôi sẽ giải thích các phương pháp cụ thể để tận dụng Swagger UI cục bộ và cách nó có thể cải thiện hiệu quả phát triển. Tôi hy vọng điều này sẽ hữu ích cho các kỹ sư tham gia vào phát triển API.

Bắt đầu chỉ trong 5 phút! Hướng dẫn thiết lập môi trường Swagger UI cục bộ

Bạn có thể nghĩ rằng "Có vẻ phức tạp...", nhưng thực tế, việc thiết lập môi trường Swagger UI cục bộ đơn giản đến ngạc nhiên. Với các bước sau đây, bạn có thể hoàn thành thiết lập chỉ trong khoảng 5 phút.

Bước 1: Lấy Swagger UI

Cách đơn giản nhất là clone repository từ GitHub:

git clone https://github.com/swagger-api/swagger-ui.git

Bước 2: Chuẩn bị một web server đơn giản

Với điều kiện Node.js đã được cài đặt, hãy cài đặt http-server toàn cục:

npm install -g http-server

Bước 3: Khởi động server

Di chuyển đến thư mục phân phối của Swagger UI và khởi động server:

cd swagger-ui/dist
http-server --cors

Tùy chọn --cors được sử dụng để bật Cross-Origin Resource Sharing.

Bước 4: Truy cập qua trình duyệt

Truy cập http://localhost:8080 trong trình duyệt của bạn để xem giao diện Swagger UI.

Bước 5: Chuẩn bị tệp đặc tả API

Dưới đây là ví dụ về tệp đặc tả Swagger tối thiểu (lưu dưới dạng swagger.yaml):

openapi: 3.0.0
info: title: API Mẫu version: 1.0.0
paths: /hello: get: summary: API trả về lời chào responses: '200': description: Phản hồi thành công content: application/json: schema: type: object properties: message: type: string

Bước 6: Hiển thị tệp đặc tả trong Swagger UI

Nhập URL của tệp đặc tả cục bộ (ví dụ: http://localhost:8080/swagger.yaml) vào hộp nhập liệu ở đầu màn hình Swagger UI, sau đó nhấp vào nút "Explore".

Với các bước trên, bạn có thể tạo và xem tài liệu API bằng Swagger UI trong môi trường cục bộ. Phương pháp này cho phép bạn tạo và chỉnh sửa tài liệu API ngay cả khi không có kết nối internet hoặc trong môi trường có yêu cầu bảo mật nghiêm ngặt.

Ví dụ thực tế về việc sử dụng Swagger UI cục bộ: Từ trải nghiệm của tôi

Ví dụ 1: Xử lý thay đổi đặc tả API trong chuyến công tác

Như tôi đã đề cập trước đó, lần đầu tiên tôi thực sự nhận ra giá trị của việc sử dụng Swagger UI cục bộ là trong chuyến công tác. Trong cuộc họp với khách hàng, chúng tôi quyết định thay đổi đặc tả và tôi cần cập nhật tài liệu API ngay tại chỗ.

Mặc dù Wi-Fi của khách sạn không ổn định, nhưng với Swagger UI cục bộ, tôi đã có thể:

Chỉnh sửa tệp YAML theo yêu cầu của khách hàng
Phản ánh các thay đổi ngay lập tức trên server cục bộ
Cho khách hàng xem tài liệu đã cập nhật ngay tại chỗ

Quá trình diễn ra suôn sẻ và tôi vẫn nhớ cảm giác ngạc nhiên: "Wow, cái này thực sự tiện lợi!"

Ví dụ 2: Sử dụng trong dự án có yêu cầu bảo mật nghiêm ngặt

Trong một trường hợp khác, tôi làm việc trong một dự án tài chính với chính sách bảo mật hạn chế việc sử dụng các dịch vụ bên ngoài. Chúng tôi không thể quản lý tài liệu API bằng các công cụ trực tuyến, nhưng với việc sử dụng Swagger UI cục bộ, chúng tôi đã có thể:

Quản lý an toàn đặc tả API chứa thông tin nhạy cảm
Chia sẻ đặc tả trong nhóm thông qua repository Git
Tích hợp với pipeline CI/CD để tự động tạo và xác thực tài liệu

Hiểu cơ bản về Swagger UI: Hình thức mới của tài liệu API

Hãy quay lại kiến thức cơ bản và giải thích ngắn gọn về Swagger UI.

Swagger UI là công cụ hiển thị và xác thực trực quan các định nghĩa API được viết bằng OpenAPI Specification (trước đây gọi là Swagger Specification). Đây là dự án mã nguồn mở được phát triển bằng JavaScript với các đặc điểm sau:

Biểu diễn API trực quan: Hiển thị định nghĩa API được viết bằng YAML/JSON theo cách dễ đọc
Xác thực tương tác: Có thể gửi yêu cầu API thực tế để kiểm tra hoạt động
Tích hợp tài liệu và kiểm thử: Đặc tả và kiểm thử được kết hợp

Sức hấp dẫn lớn nhất của Swagger UI là khả năng "cung cấp tài liệu API không chỉ là văn bản đơn thuần mà còn là trải nghiệm tương tác".

Đào sâu vào lợi ích của việc sử dụng cục bộ: Tại sao nên sử dụng offline?

Hãy xem xét chi tiết hơn về lợi ích của việc sử dụng Swagger UI cục bộ.

1. Bảo mật và quyền riêng tư

Bảo vệ thông tin nhạy cảm: Tránh rủi ro tiết lộ API nội bộ ra bên ngoài
Tuân thủ quy định: Có thể sử dụng an toàn trong các ngành có quy định nghiêm ngặt (tài chính, y tế)
Bảo vệ IP: Giảm rủi ro rò rỉ thiết kế API cho đối thủ cạnh tranh

2. Tự do làm việc offline

Phát triển không phụ thuộc địa điểm: Có thể làm việc khi di chuyển hoặc ở nơi có kết nối không ổn định
Không phụ thuộc mạng: Không bị ảnh hưởng bởi sự cố dịch vụ đám mây
Đảm bảo tính liên tục: Chuyển đổi liền mạch giữa online và offline

3. Hiệu suất và khả năng phản hồi

Phản hồi nhanh: Cải thiện trải nghiệm người dùng do không có độ trễ mạng
Hiệu quả tài nguyên: Tận dụng tối đa tài nguyên cục bộ
Xử lý định nghĩa API lớn: Vận hành mượt mà ngay cả với định nghĩa API phức tạp

4. Tích hợp với quy trình phát triển

Tích hợp với quản lý phiên bản: Dễ dàng quản lý định nghĩa API với VCS như Git
Tích hợp với CI/CD: Dễ dàng tích hợp vào quy trình kiểm thử và xác thực tự động
Tăng hiệu quả phát triển nhóm: Nhà phát triển front-end và back-end tham chiếu cùng một đặc tả

Nâng cao: Kỹ thuật sử dụng Swagger UI cục bộ chuyên sâu

Dưới đây là một số kỹ thuật nâng cao để tận dụng tối đa môi trường Swagger UI cục bộ.

Kỹ thuật 1: Áp dụng chủ đề tùy chỉnh

Bạn có thể tùy chỉnh thiết kế Swagger UI cho phù hợp với dự án của mình. Chỉnh sửa swagger-ui/dist/swagger-ui.css hoặc thêm CSS tùy chỉnh để tạo chủ đề phù hợp với màu thương hiệu của bạn.

Kỹ thuật 2: Chuyển đổi giữa nhiều môi trường

Để chuyển đổi giữa các định nghĩa API cho nhiều môi trường như phát triển, kiểm thử và sản xuất, bạn có thể tạo tệp HTML như sau:

<!DOCTYPE html>
<html>
<head> <title>Tài liệu API</title> <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
</head>
<body> <div id="swagger-ui"></div> <script src="./swagger-ui-bundle.js"></script> <script> window.onload = function() { const ui = SwaggerUIBundle({ urls: [ {url: "specs/dev.yaml", name: "Môi trường phát triển"}, {url: "specs/test.yaml", name: "Môi trường kiểm thử"}, {url: "specs/prod.yaml", name: "Môi trường sản xuất"} ], dom_id: '#swagger-ui', deepLinking: true, presets: [SwaggerUIBundle.presets.apis], }); window.ui = ui; }; </script>
</body>
</html>

Kỹ thuật 3: Kết hợp với máy chủ giả lập

Kết hợp Swagger UI với máy chủ giả lập cho phép bạn kiểm tra hoạt động của API mà không cần backend thực tế. Ví dụ, bạn có thể kết hợp swagger-ui với json-server:

npm install -g json-server
json-server --watch mock-data.json --routes routes.json --port 3000

Sau đó, cấu hình phần servers trong tệp định nghĩa Swagger UI như sau:

servers: - url: http://localhost:3000 description: Máy chủ giả lập

Quay lại cơ bản: Các phương pháp tốt nhất cho thiết kế API hiệu quả

Để tận dụng tối đa Swagger UI, thiết kế API chất lượng là không thể thiếu. Hãy xem lại các phương pháp tốt nhất cho thiết kế API hiệu quả.

1. Quy tắc đặt tên nhất quán

Sử dụng danh từ số nhiều cho endpoint (ví dụ: /users, /products)
Biểu thị thao tác bằng phương thức HTTP (GET, POST, PUT, DELETE)
Phân biệt rõ ràng giữa tham số truy vấn và tham số đường dẫn

2. Sử dụng mã trạng thái HTTP phù hợp

Dải 200: Thành công (200 OK, 201 Created, 204 No Content)
Dải 400: Lỗi phía khách hàng (400 Bad Request, 404 Not Found)
Dải 500: Lỗi phía máy chủ (500 Internal Server Error)

3. Tài liệu chi tiết

Nêu rõ mục đích và ví dụ sử dụng cho mỗi endpoint
Cung cấp ví dụ về yêu cầu/phản hồi
Giải thích các trường hợp lỗi và cách xử lý

Việc áp dụng các phương pháp tốt nhất này trong thiết kế API sẽ giúp bạn tận dụng tối đa giá trị của Swagger UI.

So sánh với các công cụ khác: Lựa chọn Apidog

Swagger UI là một công cụ tuyệt vời, nhưng nếu bạn đang tìm kiếm môi trường phát triển API tích hợp hơn, Apidog là một lựa chọn đáng cân nhắc.

Apidog là công cụ cung cấp thiết kế API, tạo tài liệu, kiểm thử và chức năng máy chủ giả lập trong một nền tảng duy nhất. Nó có thể nhập trực tiếp tệp đặc tả Swagger/OpenAPI và cho phép bạn bắt đầu sử dụng ngay mà không cần thiết lập phức tạp.

Các tính năng chính của Apidog

Giao diện trực quan: Thiết kế API bằng kéo và thả
Chức năng kiểm thử tích hợp: Thực hiện kiểm thử API cùng nơi với tài liệu
Hợp tác nhóm: Chỉnh sửa đồng thời và quản lý quyền
Tài liệu đẹp mắt: Tài liệu công khai có thể tùy chỉnh

Cá nhân tôi sử dụng Swagger UI cho các dự án nhỏ và Apidog cho các dự án phát triển nhóm lớn. Cả hai đều là công cụ tuyệt vời, vì vậy bạn nên chọn theo quy mô và yêu cầu của dự án.

Tóm tắt: Tối đa hóa hiệu quả phát triển với Swagger UI cục bộ

Trong bài viết này, tôi đã giải thích cách tận dụng Swagger UI trong môi trường cục bộ, kèm theo các ví dụ thực tế.

Tóm tắt các điểm chính:

Sử dụng Swagger UI cục bộ cho phép phát triển API trong môi trường offline và môi trường có yêu cầu bảo mật nghiêm ngặt
Thiết lập rất đơn giản, chỉ cần clone từ GitHub và khởi động một web server đơn giản
Trong thực tế, nó cho phép phát triển API linh hoạt ngay cả khi đi công tác hoặc trong môi trường có bảo mật nghiêm ngặt
Nắm vững các phương pháp tốt nhất cho thiết kế API cơ bản sẽ giúp bạn tận dụng Swagger UI hiệu quả hơn
Tùy thuộc vào quy mô và yêu cầu của dự án, việc sử dụng kết hợp Swagger UI với các công cụ như Apidog cũng là một chiến lược tốt

Việc sử dụng Swagger UI cục bộ có thể cải thiện đáng kể hiệu quả và chất lượng phát triển API. Hãy thử ngay!

Nếu bạn có ý tưởng "Tôi cũng có thể sử dụng nó theo cách này!", hãy chia sẻ trong phần bình luận. Hãy cùng nhau giải quyết các vấn đề trong việc tạo tài liệu API!