I'm thinking that this probably needs to slot in on http://doc.wikimedia.org somewhere.

I think that the swagger docs should be exposed by restbase itself, so that they are up to date with the code and configuration that's running. I'm not sure if we want other docs at this point. Tutorial style content could be useful, but that should perhaps live on mediawiki.org.

It makes sense for restbase to expose its own spec, but the spec should be static and curated by the team, as opposed to dynamic and generated by restbase at runtime. This way we get all the benefits of DbC, TDD, contract-first development.

See also: https://github.com/wikimedia/restbase/issues/1#issuecomment-64021262

@Jdouglas: Agreed. Separate swagger specs with an API-only layer plus spec-driven testing should help to ensure this.

We now have a way to create static/offline documentation from a Swagger JSON spec. The output is a single HTML file that looks like this: http://wikimedia.github.io/restbase/v1/

To use it, we can wire up a curl command into our CI process, once we get a docs repo going:

curl swagger-doc.herokuapp.com/html -X POST -d @/path/to/swagger.json > index.html

It might be worth running this service ourselves, so we don't rely on an external connection during CI.