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

Question

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

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

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

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

Answer 1

如果您的 API 使用 oAuth 身份验证，您可以为此使用范围。在 Swagger/OpenApi 中没有针对基本身份验证表示角色的标准方法，因此您只能使用供应商扩展(如您发现的那样，Swagger-UI 或 swagger2markup 等工具无法解释)，或者包括信息为 summary 中的文本或 description特性。

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

另见本期 https://github.com/OAI/OpenAPI-Specification/issues/1366建议将范围的使用范围扩大到其他安全方案。