How to define role/permission security in Swagger

Question

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?

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.

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

What's the best way to document the role and permission information per endpoint?

Solution

If your API uses oAuth authentication, you can use scopes for this. There is no standard way to represent roles in Swagger/OpenApi against basic authentication, so you are left using vendor-extensions (which the tools such as Swagger-UI or swagger2markup have no way of interpreting, as you have found), or including the information as text in summary or description properties.

You could define multiple securityDefinitions all of type basic and use one per role but this is a bit of a hack.

See also this issue https://github.com/OAI/OpenAPI-Specification/issues/1366 for a proposal to widen the use of scopes to other security schemes.

Comments

[whatsTheDiff]

I see description in the spec but don't see synopsis. Which version is it available in? Either way, unfortunately, those only seem to get displayed in the generic Security block and not with each API call which would be more ideal. It looks like defining the scope with basic is allowed with swagger2markup but is against the spec, so I can "hack" that to get it to be more like I would hope - but still not ideal.

[MikeRalphson]

Sorry, I was thinking of 'summary' not 'synopsis', this would be at the operation level though, not securityDefinition.