Improved generated protocol documentation

[codingchili]

• [x] use YAML instead of JSON for readability.
• [x] map route path to route info for readability (the info is nested)

Good:

---
description: "A simple highscore API."
routes:
  update:
    description: "Updates the highscore entries with the given entry."
    model:
      score: "java.lang.Integer"
      player: "java.lang.String"
    roles:
    - "PUBLIC"
  list:
    description: "Returns a list of the current highscore selection."
    roles:
    - "PUBLIC"

Bad:

{
  "model" : { },
  "text" : "A simple highscore API.",
  "routes" : [ {
    "model" : {
      "score" : "java.lang.Integer",
      "player" : "java.lang.String"
    },
    "description" : "Updates the highscore entries with the given entry.",
    "role" : [ "PUBLIC" ],
    "name" : "update"
  }, {
    "model" : { },
    "description" : "Returns a list of the current highscore selection.",
    "role" : [ "PUBLIC" ],
    "name" : "list"
  } ],
  "status" : "ACCEPTED",
  "target" : "api",
  "route" : "documentation"
}

• [x] empty objects
• [x] json is not readable enough
• [x] order of fields are not intuitive
• [x] response headers should be removed

[codingchili]

future notes

• [x] the api 'target' aka 'base path' is not include din the API documentation.
  • the protocol does not have access to this information.
  • can be retrieved from annotation? + programmatically set? avoid changing ctor.
• [x] cache serialization/buffer? protocol can internally check dirty state.

[codingchili]

• [x] update the documentation on this feature.

[codingchili]

• [x] javadoc the documentation generators
• [x] document that api generators can be used directly.

[codingchili]

• [x] don't include synthetic fields in Serializer#describe, for example when describing inner classes.

[codingchili]

waiting for tests bff1d7754d8e638ae455573f338512efdb8cd5ce

[codingchili]

Tests passed.