REST service documentation

[stuartlewis]

We need to provide REST documentation - perhaps via the root webpage of the datavault-broker web application?

[stuartlewis]

JSONDOC (http://jsondoc.org/) integrated. Now all controllers and models need annotating.

[tomhigginsuom]

I've noticed that JSONDOC doesn't appear to respect @JsonIgnore annotations - so it can include fields which are not actually part of the REST objects which are sent/received. One way around this might be to split our objects so that they have an "interface" object with the required fields for dealing with API clients and a "data model" object which represents what is stored in the DB.

For example, some relationships, IDs and properties won't be known to the API client when creating an object. What appears to the API client as an opaque ID ("Vault ID" for a deposit) is actually an object reference once it's inside the broker.

[stuartlewis]

Hmmm... interesting: Removing the jsondoc annotation from the jsonignore'd fields removes it from the table, but not the json on the right hand side of the page.

I've submitted this to the JSONDOC project - and I'll see if they can do that:

• @JsonIgnore not ignored fabiomaffioletti/jsondoc#159