Swagger là một công cụ đặc biệt tự động soạn tài liệu RESTful API cho ứng dụng của bạn.
Ưu điểm của nó nằm ở chỗ nó cho phép bạn không chỉ xem qua tất cả các điểm cuối của ứng dụng mà còn có thể ngay lập tức kiểm tra hoạt động của chúng bằng cách gửi yêu cầu và nhận phản hồi.
Để truy cập Swagger , bạn cần nhấn vào nút Preview trong ứng dụng đã xuất bản và nhấp vào tên của kế hoạch xuất bản được yêu cầu ( Deploy Plan ).
Trong cửa sổ mới mở, danh sách các điểm cuối có sẵn và các phương thức được liên kết với các điểm cuối này được hiển thị. Một số yêu cầu chỉ khả dụng cho một số nhóm người dùng được ủy quyền nhất định (xem Phần mềm trung Middleware của Auth module thực cho từng yêu cầu cụ thể trong phần Endpoints ). Cần có Bearer Token thông báo mang cho các yêu cầu chỉ được phép cho người dùng được ủy quyền.
Bạn có thể truy cập trực tiếp vào điểm cuối tương ứng trong Swagger để nhận mã thông báo này ( phần Auth thực, yêu cầu POST /auth ).
Nhấn Try it out và nhập thông tin đăng nhập và mật khẩu để nhận mã thông báo.
Yêu cầu sẽ được gửi trên Execute . Nếu thành công, bạn sẽ thấy trường token thông báo có giá trị Bearer token .
Cách thứ hai để nhận mã thông báo người dùng được ủy quyền là mã thông báo có thể được tìm thấy trong phần yêu cầu của ứng dụng đã triển khai.
- Nhấn F12 trong trình duyệt web của bạn để mở công cụ của nhà phát triển.
- Gửi bất kỳ yêu cầu nào trong ứng dụng đã triển khai của bạn (ví dụ: để cập nhật các bảng). Người dùng đang gửi yêu cầu này phải được ủy quyền để truy cập điểm cuối này.
- Mở tab Network và tìm yêu cầu tương ứng.
- Chuyển đến tab Headers và tìm phần Request Headers . Bearer token sẽ được trình bày dưới Authorization .
Cung cấp Bearer token cho Swagger bằng cách nhấn Authorize và dán giá trị bạn đã sao chép ở bước trước.
Đối với các yêu cầu thử nghiệm, hãy chọn nhóm mong muốn và phương pháp bạn muốn thực hiện. Nhấn Try it out và điền các thông số đầu vào yêu cầu. Nhấp vào Execute để thực hiện phản hồi.
Phản hồi được mong đợi nhất, nếu yêu cầu được máy chủ xử lý chính xác, có mã 200 và hiển thị cấu trúc phản hồi sẽ như thế nào.
401 - yêu cầu không được hoàn tất thành công vì mã thông báo ủy quyền bắt buộc bị thiếu hoặc không hợp lệ.
404 - yêu cầu đã được xử lý thành công nhưng không tìm thấy tài nguyên được yêu cầu.
422 - thông số không chính xác đã được chuyển đến đầu vào của yêu cầu.
500 - lỗi xử lý yêu cầu của máy chủ.
Tăng lỗi tùy chỉnh
Đối với các BP tùy chỉnh và các yêu cầu liên quan, có thể tạo mã lỗi tùy chỉnh với các mô tả bằng cách sử dụng khối Raise Error trong trình chỉnh sửa BP. Một ví dụ về quá trình như vậy là dưới đây:
Trong trường hợp này, nếu yêu cầu đến điểm cuối được liên kết với BP ở trên không thành công, máy chủ sẽ đưa ra lỗi 418 có chứa văn bản lỗi khi thực hiện khối DB: Create Candidate block . Mã lỗi trong ví dụ này có thể là bất kỳ mã nào mà người dùng chỉ định.
Lưu ý: mã phản hồi lỗi HTTP 418 I'm a teapot client cho biết rằng máy chủ từ chối pha cà phê vì nó vĩnh viễn là một ấm trà. Thay vào đó, bình cà phê/trà kết hợp tạm thời hết cà phê sẽ trả về 503. Lỗi này liên quan đến Hyper Text Coffee Pot Control Protocol được xác định trong trò đùa Cá tháng Tư năm 1998 và 2014.
