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を複数定義し、役割ごとに1つ使用することもできますが、これはちょっとしたハックです。

スコープの使用を他のセキュリティスキームに広げる提案については、この問題 https://github.com/OAI/OpenAPI-Specification/issues/1366 も参照してください。