[Suggestion] create an openapi/swagger spec for the http management api.

[paulbalomiri]

RabbitMQ series

4.2.x

Operating system (distribution) used

linux/debian

How is RabbitMQ deployed?

Community Docker image

What would you like to suggest for a future version of RabbitMQ?

I'd be happy see and invest some time into making a proper swagger definition of the existing management api.

This is a followup of

• a bug report declare stream expiration setting ignored rabbitmqadmin-ng#145
• a folloup in declare_stream does not set x-max-age from StreamParams::expiration, uses wrong key names for length args michaelklishin/rabbitmq-http-api-rs#118
• a fix in Fix three stream argument validation bugs #16284
• a second fix in By @lukebakken: Fix three stream argument validation bugs #16285

previously this topic has been touched in

• RabbitMQ Management HTTP API : Field Types #3135, where Hop (java) and rabbit-hole are mentioned.

I'd be most interested in creating tooling such that the swagger definition would be automatically kept in sync with the mgmt api. Keeping a spec in sync by hand might be inferior to the current state of api documentation in a html file.

Creating an openapi definition

It might be a good starting point to generate a replacement for the existing static documentation. The replacement would come from an openapi definition.

I have looked through the api documentation source in deps/rabbitmq_management/priv/www/api/index.html, and it seems to be maintained manually, but please correct me if i am wrong here.

Looking at the source code i see that the main URL path structure is mapped here

rabbitmq-server/deps/rabbitmq_management/src/rabbit_mgmt_dispatcher.erl

Lines 100 to 103 in 1f9b774

	dispatcher() ->
	[{"/overview", rabbit_mgmt_wm_overview, []},
	{"/cluster-name", rabbit_mgmt_wm_cluster_name, []},
	{"/nodes", rabbit_mgmt_wm_nodes, []},

I was wondering if there was a way to extract the existing response shapes from the existing source code, with tooling, to avoid a one time generated spec which would be taxing in deployment and boring during the devcycle.

Generating clients

For generating clients there are tools for many languages.

My concrete itch i'm trying to solve is to access the management Api from Elixir. ATM i'm using the rabbitmqadmin-ng client, and created a wrapper which converts atoms to commandline options to http requests. I did this for dev, but it's very brittle, and I'd much prefer to create a proper client lib with oapi_generator.

For rust there are also crates such as progenitor from which rabbitmqadmin-ng might benefit?

There might be even a case to be made to generate the server view layer from an Openapi spec with some custom spec fields, but i'm not competent enough on that subject to propose something.

So what do you think?

• is it still desirable to have an OpenApi v3 spec for the management api?
• if yes, could we generate the docs with tooling from the existing codebase, with no or only minimal interventions?