How to define role/permission security in Swagger

Question

In my API documentation, I would like to define the security necessary for each API endpoint. The project has defined roles and permissions that determine which users can access the APIs. What is the best way in Swagger to document this information? Is there a best practice or recommendation on how to show this detail?

This what I tried out using securityDefinitions and a self-defined variable for the roles, but that information (x-role-names) didn't get copied over into the documentation when I ran it through swagger2markup or using swagger-ui.

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

What's the best way to document the role and permission information per endpoint?

Answer 1

如果您的API使用oAuth身份验证，则可以使用范围。没有标准的方法来表示Swagger / OpenApi中的角色对抗基本身份验证，因此您将继续使用供应商扩展（如Swagger-UI或swagger2markup等工具无法解释，如您所找到的），或者包括信息为summary或description属性中的文字。

您可以定义多个securityDefinitions所有类型basic，并为每个角色使用一个，但这有点像黑客。

有关将范围扩展到其他安全方案的提案，请参阅此问题https://github.com/OAI/OpenAPI-Specification/issues/1366。