comments on request body

[Alexorz]

Hello guys, is there any syntax for adding some comments into the request body?

Sometimes I need to make some notes on some params in the JSON of POST request body, just like this:

+ Request (application/json)

        {
            "question": "Favourite programming language?",
            "answer": "JavaScript",     // value of `answer` must be one of these options: "Swift", "Python", "Objective-C", "Ruby", "JavaScript"
        }

But I found it will make the request body becomes an invalid JSON string in apiary.io or in dredd.

Here is the request body which was generated by apiary.io, it didn't cut out the content after //:

And dredd threw error: fail: body: Can't validate. Expected body Content-Type is application/json but body is not a parseable JSON: Parse error on line 1:

So, Is there any solutions? Or, am I doing right?

Thank you.

[kylef]

We can go one step further and actually document it using MSON and explicitly mark this value as an enum, for example:

+ Request (application/json)
    + Attributes
        + question: `Favourite programming language?` (required)
        + answer: JavaScript (enum, required)
            + Swift
            + JavaScript
            + Ruby

Using MSON, you can attach descriptions and other type-information.

With our new beta for attributes in Apiary (opt-in), you can view this as follows:

This will also generate a matching JSON Schema:

And render the example JSON payload from the example values:

Does this answer your question?

[kylef]

Also want to point out, using the enum MSON syntax, Dredd can then improve it's validation to enforce that values are inside the enum.

[Alexorz]

It works, that is pretty cool. Thank you :) And maybe I should read the doc more attentively next time...