The request payload to create a release unnecessarily accepts a URI template

[odrotbohm]

The specifications of the apiDocUrl and referenceDocUrl fields of request payload to add a new release are unnecessarily vague. There's no real need for a client to submit a {version} template variable, as it could just send an expanded URL, which would allow the type of the field to be tightened to URL.

A backwards-compatible way of supporting this would be to accept optional fields apiDoc and referenceDoc to only accept URLs if given. This step could also be used to rather let a referenceDocs expect an array of objects, each with an href and type field, to allow different types (HTML, PDF) of reference docs to be submitted.

{
  …,
  "apiDoc" : "…",
  "referenceDocs" : [
    { "href" : "…", "type" : "…" },
    { … }
  ]
}

An apiDoc would then trump apiDocUrl. A referenceDocs would trump a referenceDoc (this one defaulting to a single entry with type to HTML). A canonical response format is described in #2.

[odrotbohm]

Just for reference: I checked the Spring Data release tooling, and that sends expanded URLs for apiDocUrl and referenceDocUrl already.