Visualizing the REST API documentation
This issue isn't about how to generate a static documentation of the object based traversal that Core uses.
Suppose I come up something to generate those routes with supported HTTP methods and parameters.
What is the best way to visualize that?
One option that we had come across before was Swagger.io. All the "tools" used to build the swagger framework is open sourced. So, can we use that as "official" documentation for Mailman's REST API?
I haven't explored "Swagger UI" ( a part of tools) completely, but if you somehow provide with a JSON with all the data related to your API, it presents a sweet looking API documentation, which optionally can run against an actual API server. It looks like http://petstore.swagger.io/. I don't want the documentation to be functional i.e. run against an actual API server, but just the documentation part would be useful to have.
We would ideally generate the JSON spec using the CI infra and push it to a Git Repo which would then be served using Gitlab's static page hosting for free.
These are just my initial thoughts and it would be good to explore more options.