Documenting parameter and representation examples

[erunion]

For the API Blueprint files (and coming OAI work planned for in 2.0, #16), to be useful in a mock server environment like Drakov, we need some sort of way to document @api-param and representation data examples.

I think documenting them on representations would be easily accomplished with an @api-example annotation:

/**
 * @api-label Director
 * @api-field director
 * @api-type string
 * @api-example JJ Abrams
 */

Thankfully, this isn't really necessary for enum's as Drakov picks the first item in the enum as the example. For parameters, however, it's a bit more complicated because of the existing language syntax in place for documenting them.

The current idea that I've been running with is to document examples within backticks.

@api-param:public {string} director (optional) `JJ Abrams` Name of the director.

And compiled into the Blueprint, it would appear as:

- `director`: `JJ Abrams` (string) - Director

[agilefox]

Can drakov handle multiple examples?
If so, I would suggest allowing multiple examples so the system would work with

`@api-param:public {string} director (optional) `JJ Abrams` Name of the director.

or

`@api-param:public {string} director (optional) `JJ Abrams`,`Alfred Hitchcock`,`Lana Wachowski, Lilly Wachowski` Name of the director.

Also, didn't realize both Wachowski brothers were sisters now.

[agilefox]

Also, this has the issue of data that wouldn't go with other data could be returned. I.e. we might only return a credit notification in the NotificationResponse if the seen count is > 0.

So the specific data may be valid, but the overall could be wrong

[erunion]

1. No. API Blueprint only supports a single example.
2. Yeah I think that's a problem, but there is unfortunately no way in API Blueprint (or OAI for that matter) to document a parameter or representation data being available on a case basis (if this, then that). I think in this case, the example would just be for the most basic usage.

[erunion]

It might actually be worth just moving the @api-param DSL over to MSON and be done with it.