Document the usage of Gavel Specs

[ioggstream]

I expect

The documentation reference the usage of Gavel specifications

[jmcanterafonseca]

I'm not a big fan of intermixing concerns, i.e. add to the API specification test case definitions, those test case definitions should be in another artefact, I believe