How to define role / permission security in Swagger

Question

In my API documentation, I would like to define the security required for each API endpoint. The project defines roles and permissions that determine which users can access the API. What is the best way to document this information in Swagger? Is there any best practice or recommendation on how to show this detail?

This is what I tried using securityDefinitions and a self-defined variable for roles, but this information (x-role names) was not copied to the documentation when I ran it through swagger2markup or using swagger-ui.

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

What is the best way to document role and permission information for an endpoint?

Answer 1

If your API uses oAuth authentication, you can use for this area. There is no standard way of representing roles in Swagger / OpenApi for basic authentication, so you are left with vendor extensions (which tools, such as Swagger-UI or swagger2markup, cannot interpret as you already found), or including information as text in properties summary or description .

You can define several securityDefinitions all basic types and use one role, but this is a bit hacked.

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