Swaggerで役割/権限セキュリティを定義する方法

Question

私のAPIドキュメントでは、各APIエンドポイントに必要なセキュリティを定義したいと思います。プロジェクトには、どのユーザーがAPIにアクセスできるかを決定する役割とアクセス許可が定義されています。この情報を文書化するためのSwaggerの最善の方法は何ですか？この詳細を表示する方法に関するベストプラクティスまたは推奨事項はありますか？

securityDefinitionsと自己定義の変数を使用して試したことはありますが、swagger2markupまたはswagger2markupを使用して実行したときにその情報（x-role-names） ui。

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

エンドポイントごとの役割とアクセス許可の情報を記録するにはどうすればよいですか？

Answer 1

APIでoAuth認証が使用されている場合は、これにスコープを使用できます。 Swagger/OpenApiの基本的な認証に対する役割を表す標準的な方法はないので、ベンダー拡張機能（Swagger-UIやswagger2markupなどのツールはあなたが見つけたように解釈する方法がありません）を使うか、情報はsummaryまたはのテキストとして表示されます。

タイプbasicの複数のsecurityDefinitionsを定義し、ロールごとに1つ使用することができますが、これは少しハックです。

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