Defining role/permission security

[Diff]

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?  I researched the option of using securityDefinitions and using a self-defined variable for the roles, but that information didn't get copied over into the documentation when I ran it through swagger2markup or using the Swagger UI.  Is there a best practice or recommendation on how to show this detail?

[Tamer Shahin]

I'm quite interested in this as well!

is there any way (within the same swagger file) to create a set of basic endpoints available as open/public API and a superset for private/internal use only. 

Thanks!

[tony tam]

Hi, yes, you would create multiple securityDefinition objects--see here for details on that structure.

Then, on each operation that is secured, assign the required security, which references your security definitions.  There is an example in the http://petstore.swagger.io/v2/swagger.json application.

[Tamer Shahin]

Cool thanks,

I'm planning to use JWT, so the api_key approach def will fit properly!

My main problem is that scopes are defined only for OAUTH approach.

JWT supports the notion of scopes, so it would be great to see this for api_key as well (or a new profile JWT)

what do you think?

T

[Diff]

Does this apply though if you're using other types of authentication?  We're not using oauth2 in our project.