How to define role/permission security in Swagger : <p>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?</p>

<p>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.</p>

<pre><code>    "securityDefinitions": {
    "baseUserSecurity": {
          "type": "basic",
          "x-role-names": "test"
       }
    }
</code></pre>

<p>What's the best way to document the role and permission information per endpoint?</p>
