Allow to describe a response in plain Markdown
I'm using the new *X-1A* syntax which supports multiple responses, though only when the response code is different (could not manage to have responses with the same response code; please let me know how to accomplish this).
Since there are multiple response going one after another, in the rendered examples view it is difficult for an API user (not API developer) to quickly understand the difference between each responses since they all refer to the same request resource. It would be nice to optionally allow to describe each response in plain Markdown syntax.
This is possible to do in the new format, but we are not displaying this properly in the old documentation.
We certainly plan to fix this and I’ll keep you posted once it’s live.
AdminZ (Admin, apiary.io) commented
Absolutely. You can already discuss respective payload (requests, responses and models) in API Blueprint as specified here: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#Payload – see "Example (request payload section)"
However as Lukas mentions, it is displayed in the current Apiary rendered documentation.
We are working around the clock to bring you the new, completely redesigned, documentation that will fully capture every aspect of the new format.
Esen Sagynov commented
I would be happy if you let me know how to do this in the new format. Even though you don't want to open this publicly yet, if it is possible to use it, please let me know.