Swagger là gì và cách sử dụng nó | AppMaster

Posted on by mtoplistChuyên mục:Top List

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 ).

swagger access

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 ).

swagger authorize

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.

  1. Nhấn F12 trong trình duyệt web của bạn để mở công cụ của nhà phát triển.
  2. 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.
  3. Mở tab

    Network

    và tìm yêu cầu tương ứng.

  4. Chuyển đến tab

    Headers

    và tìm phần

    Request Headers

    .

    Bearer token

    sẽ được trình bày dưới

    Authorization

    .

bearer token

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.

response 200

  • 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ệ.

    response 401

  • 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.

    response 404

  • 422 – thông số không chính xác đã được chuyển đến đầu vào của yêu cầu.

    response 1200

  • 500 – lỗi xử lý yêu cầu của máy chủ.

    response 500

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:

example

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.

mtoplist