Cách xác định bảo mật vai trò/quyền trong Swagger

Question

Trong tài liệu API của tôi, tôi muốn xác định tính bảo mật cần thiết cho mỗi điểm cuối API. Dự án đã xác định vai trò và quyền xác định người dùng nào có thể truy cập API. Cách tốt nhất trong Swagger để ghi lại thông tin này là gì? Có thực hành hay đề xuất hay nhất về cách hiển thị chi tiết này không?

Đây là những gì tôi đã thử bằng cách sử dụng định nghĩa bảo mật và biến tự định nghĩa cho vai trò, nhưng thông tin đó (x-role-name) không được sao chép vào tài liệu khi tôi chạy nó qua swagger2markup hoặc sử dụng swagger- ui.

"securityDefinitions": { 
    "baseUserSecurity": { 
      "type": "basic", 
      "x-role-names": "test" 
     } 
    } 

Cách tốt nhất để ghi lại thông tin vai trò và quyền cho mỗi điểm cuối là gì?

Answer 1

Nếu API của bạn sử dụng xác thực oAuth, bạn có thể sử dụng phạm vi cho việc này. Không có cách tiêu chuẩn để đại diện cho vai trò trong Swagger/OpenApi so với xác thực cơ bản, do đó bạn được sử dụng các phần mở rộng của nhà cung cấp (các công cụ như Swagger-UI hoặc swagger2markup không có cách diễn giải, như bạn đã tìm thấy), hoặc bao gồm thông tin dưới dạng văn bản trong các thuộc tính summary hoặc description.

Bạn có thể xác định nhiều securityDefinitions tất cả các loại basic và sử dụng một cho mỗi vai trò nhưng đây là một chút của một hack.

Xem thêm vấn đề này https://github.com/OAI/OpenAPI-Specification/issues/1366 cho đề xuất mở rộng việc sử dụng phạm vi cho các đề án bảo mật khác.