Giới thiệu

Swagger UI là một trong những giải pháp phổ biến nhất để cung cấp tài liệu chức năng cho các API của bạn. Nó không chỉ là một tài liệu để đọc mà còn cho phép bạn thử nghiệm các yêu cầu và nhận phản hồi mẫu. Trong bài viết này, chúng ta sẽ khám phá cách tạo một giao diện Swagger UI đơn giản chỉ bằng HTML mà không cần phải tải xuống và lưu trữ các phụ thuộc bên ngoài.

Tại sao nên sử dụng Swagger UI?

• Tính tương tác: Swagger UI cung cấp giao diện người dùng tương tác, cho phép lập trình viên thử nghiệm API ngay lập tức.
• Dễ dàng chia sẻ: Với Swagger UI, bạn có thể chia sẻ tài liệu API với đồng nghiệp mà không cần phải có máy chủ backend.
• Hỗ trợ OpenAPI: Swagger UI tương thích với các tài liệu OpenAPI, giúp tiêu chuẩn hóa cách mô tả các API.

Cách thiết lập Swagger UI trong HTML

Bước 1: Nhúng các tệp CSS và JavaScript

Để bắt đầu, bạn chỉ cần hai tệp: một tệp CSS và một tệp JavaScript. Dưới đây là cách nhúng chúng:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui.min.css" integrity="sha512-QIJpSy6rqOKoEjIR+Pp7r5lTkNPJPJCRejWzG4jb12bCT1EeL/vcjZtk4NNKeEuVRXY+d34d/t9y1CHzZbgeJQ==" crossorigin="anonymous" referrerpolicy="no-referrer">
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui-bundle.min.js" integrity="sha512-uRL0dWo7kTNu+5ZwjyjVBt1Seg5JM14NX0Yo3nToKUVJPLINpNYvFrOYQq2ALBxRMCSMT4vSAexXYDUp5Qbt/A==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

Bước 2: Tạo phần tử HTML

Bạn cần tạo một phần tử HTML để hiển thị giao diện Swagger UI:

<div id="swagger-ui"></div>

Bước 3: Cấu hình Swagger UI

Sau khi đã tạo phần tử HTML, bạn cần thêm mã JavaScript để cấu hình Swagger UI:

<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>

Ở đây, bạn có thể thay thế URL của tài liệu OpenAPI bằng của riêng bạn. Swagger UI sẽ sử dụng tài liệu này để tạo giao diện tương tác.

Các Tham số Cấu hình Quan trọng

Swagger UI cung cấp nhiều tham số để tùy chỉnh trải nghiệm người dùng:

• url: Đường dẫn đến tài liệu OpenAPI của bạn.
• dom_id: ID của phần tử HTML mà bạn muốn hiển thị Swagger UI.

Thực hành tốt nhất

• Sử dụng định dạng YAML: Định dạng YAML thường dễ đọc hơn JSON. Hãy thử sử dụng nó trong tài liệu OpenAPI của bạn.
• CORS: Đảm bảo API của bạn được cấu hình đúng để tránh các vấn đề liên quan đến CORS.

Những cạm bẫy thường gặp

• Thiếu xác thực: Nếu API của bạn yêu cầu xác thực, hãy chắc chắn rằng bạn đã cấu hình đúng.
• Vấn đề với CORS: Nếu bạn gặp khó khăn trong việc kết nối đến API, hãy kiểm tra cấu hình CORS của máy chủ.

Mẹo Tối ưu hóa Hiệu suất

• Sử dụng dịch vụ CDN: Như đã đề cập, sử dụng cdnjs giúp giảm tải cho máy chủ của bạn.
• Giảm thiểu tần suất gọi API: Hãy xem xét cách bạn gọi API để tránh tải không cần thiết.

Khắc phục sự cố

Nếu bạn gặp phải sự cố khi thiết lập Swagger UI, hãy kiểm tra:

• Console của trình duyệt: Kiểm tra xem có lỗi nào xuất hiện không.
• Cấu hình API: Đảm bảo rằng API của bạn đang chạy và có thể truy cập được từ địa chỉ được chỉ định.

Kết luận

Swagger UI là một công cụ mạnh mẽ giúp bạn cung cấp tài liệu API một cách chuyên nghiệp và dễ dàng. Với hướng dẫn này, bạn đã có thể tạo một giao diện Swagger UI trong HTML mà không cần phải cấu hình máy chủ. Hãy thử nghiệm và chia sẻ với đồng nghiệp của bạn.

Nếu bạn có bất kỳ câu hỏi nào hoặc cần thêm thông tin, hãy để lại câu hỏi bên dưới!

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

1. Swagger UI có miễn phí không?
Có, Swagger UI là mã nguồn mở và miễn phí sử dụng.

2. Tôi có thể sử dụng Swagger UI cho API cần xác thực không?
Có, Swagger UI hỗ trợ xác thực OAuth 2.0 và api-key.

3. Làm cách nào để chia sẻ tài liệu Swagger UI với người khác?
Bạn chỉ cần cung cấp liên kết đến tệp HTML mà bạn đã tạo.

Tài nguyên tham khảo

• Swagger UI Documentation
• OpenAPI Specification

Hãy bắt đầu tạo tài liệu API của bạn ngay hôm nay!