Document permissions required for API endpoints

[artandor]

As explained in the title, the current documentation lack of informations about which permissions are required to call certain API routes. It could be a huge improvement for users to just need a quick look at a route to know what are the requirements.

It could be done in the current table present at localhost:15672/api, but it seems to me that this UI could be improved a lot by providing a Swagger UI. That would allow what i previously said, and also allow a quick display of possible parameters AND a quick way to test a route.

[artandor]

Is the file to update this one ? @michaelklishin
Is there a specific place that those infos would be all referenced ?

Considering the change of title i guess including swagger UI is off topic for now ?

[michaelklishin]

We'd consider a contribution of a Swagger reference. On this team, one issue equals one specific actionable item ("extend the docs to cover X"), not two or more ("extend the docs and provide a Swagger reference").

The page is under priv/www. Every endpoint module has a function that determines if the caller has sufficient HTTP API permissions, here's one example. Protocol method permissions are listed in a table in the docs.

[michaelklishin]

Some HTTP API endpoints are not tied to any respective AMQP 0-9-1 methods, so their permissions come down to whether the user is tagged appropriately. Others are tied to protocol methods, in which case their permission docs should be taken from the main permission table.

[artandor]

Thanks for the informations. Considering that the permissions informations are needed before trying to implement a swagger ui, i think i'll focus on updating the api documentation if I find the time to contribute.

[artandor]

Hi, I started a branch to solve this issue : https://github.com/artandor/rabbitmq-management/tree/document_permissions_api
Could anyone explain to me where can i know what vhost permissions are needed for a specific route or http verb ? For example on the route /api/bindings/vhost/e/exchange/q/queue i know that to post you need management tag + vhost permission write. But on the code side all i can find is "is_authorized_vhost", which doesn't include the "write permission" as far as i know.

[michaelklishin]

Protocol permissions are checked in rabbit_channel. A much easier approach would be to list what protocol operations an endpoint involves and then using the permission matrix in the docs.