Feature req: live swagger doc

[pswenson]

IMO prometheus should have live/interactive swagger doc for the API ala: http://petstore.swagger.io

[brian-brazil]

@fabxc Do we have this now?

[krasi-georgiev]

I have used swagger and I find it super useful.
It enforces consistent api structure and the online UI parser http://petstore.swagger.io can be used to test the api.

The current v2 protobuf file is used to auto-generated swagger definition swagger.json for the admin api so for v2 this would come out of the box(as long as you use the REST gateway, doesn't support grpc).

for v1 we would need to write the swagger definition which will generate the go skeleton and just need to implement each function. It would be a bit of work as it also enforces its own types.
It is a standardised so for long term api support might be worth the hassle.

I think it also handles api versioning quite well.

The only drawback I remember was that the auto-generated function names and data types tend to become rather long and difficult to edit without a proper IDE auto-completion support.

[krasi-georgiev]

btw it also autogenerates the docs for the api so it saves a ton of work there.
docker uses swagger for their api
all of this is auto generated form the swagger spec file - yaml
https://docs.docker.com/engine/api/v1.36/

[fkromer]

Would be great if one could auto generate clients for the Query HTTP API e.g. for Python with bravado. That would save tons of work as well 😉