Page MenuHomePhabricator

Documentation location and deployment process
Closed, DuplicatePublic

Description

RESTBase will include several types of documentation:

  • a Swagger specification e.g. swagger.json
  • a browser-based tool for API discovery (e.g. Swagger UI)
  • tutorial and examples
  • static HTML API docs
  • etc.
  • Figure out where docs will be hosted (e.g. doc.wikimedia.org)
  • Figure out where docs will be version controlled (e.g. a special branch)
  • Figure out how changes will be deployed

Related Objects

View Standalone Graph
This task is connected to more than 200 other tasks. Only direct parents and subtasks are shown here. Use View Standalone Graph to show more of the graph.
StatusAssignedTask
Resolved GWicke
Duplicate Jdouglas

Event Timeline

Jdouglas raised the priority of this task from to Normal.
Jdouglas updated the task description. (Show Details)
Jdouglas added a project: RESTBase.
Jdouglas changed Security from none to None.
Jdouglas added subscribers: Aklapper, Jdouglas.
RobLa-WMF added subscribers: Qgil, Spage.
RobLa-WMF added a subscriber: RobLa-WMF.

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

GWicke added a subscriber: GWicke.EditedDec 17 2014, 10:40 PM

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.

Jdouglas raised the priority of this task from Normal to High.Dec 18 2014, 5:43 PM

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.