如何在Swagger中定义角色/权限安全

Question

在我的API文档中，我想定义每个API端点所需的安全性。该项目定义了角色和权限，用于确定哪些用户可以访问API。在Swagger中记录此信息的最佳方式是什么？关于如何显示此详细信息，是否有最佳实践或建议？

这就是我使用securityDefinitions和角色的自定义变量进行尝试的方法，但是当我通过swagger2markup或使用swagger-ui运行它时，这些信息(x角色名称)没有被复制到文档中。

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

记录每个端点的角色和权限信息的最佳方式是什么？

Answer 1

如果您的应用编程接口使用oAuth身份验证，则可以使用作用域。在Swagger/OpenApi中没有针对基本身份验证来表示角色的标准方法，因此只能使用供应商扩展(如Swagger-UI或swagger2markup等工具无法解释的扩展)，或者将信息作为文本包含在summary或description属性中。

您可以定义多个basic类型的securityDefinitions，并为每个角色使用一个，但这有点麻烦。

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