We probably have to switch the reference server away from Flask,
single it doesn't support chucked HTTP that will be required for
streaming.

bwalsh notifications@github.com writes:

It would be useful to have the api documented using a modern interactive
approach.
This might be a topic for the meeting in NYC?
see https://github.com/gangverk/flask-swagger

—
Reply to this email directly or view it on GitHub.*

This is pretty cool @bwalsh, it would be a really neat feature. I have two slight concerns:

1. As @diekhans, we might have to move away from Flask when we start making a streaming protocol as WSGI doesn't support HTTP chunked encoding (which is ridiculous, but what can you do).
2. Our API isn't particularly clean REST, and might not fit into what's expected from a REST documentation generator.

No reason we can't play around with it and see what happens though!

See http://rest.ensembl.org/documentation/info/gacallSet for another example

See http://ga4gh-demo.westus.cloudapp.azure.com for another example.

The current state of work is reflected here. I propose future discussion about API descriptions happen there, or in the schemas. @bwalsh @jeromekelleher , OK to close?

I'm happy to close this as we've moved on a long way from this point now.

I notice the link above points to one of your repos @david4096 --- is there an official GA4GH repo for this? We should have one, it's a great documentation/developer tool that anyone should be able to deploy against any GA4GH server.

@jeromekelleher Not yet, and I agree! I expect that after we migrate to protocol buffers we will automate some part of generating API descriptions.

OK, I'm going to close this issue then as we're decoupling this from the ref server.

Although the UI isn't maintained with this code, we should provide a way to easily serve static API documentation.

Currently not working for 1kgenomes.ga4gh.org