Provide a description of each answer that we have in Apiary.io

Question

Can I provide a description for each response to a request? Suppose we have a request

### Retrieve resource [GET] + Headers If-None-Match: "Version1" 

And 2 answers

 + Response 200 (application/xml) + Headers ETag: "Version2" + Body <Xml> <A> <B /> <C /> </A> </Xml> + Response 304 (application/xml) 

I would like to provide a description like here (note the comments right below the + Response lines):

 + Response 200 (application/xml) In case if the resource hasn't changed + Headers ETag: "Version2" + Body <Xml> <A> <B /> <C /> </A> </Xml> + Response 304 (application/xml) In case if the resource has changed 

Is it possible?

Answer 1

There is currently no way to express this logic in the Blueprint API. You can always describe it “by mouth” in the corresponding answers or under the action of the action itself. For example:

 # Resource [/1] ## Action [GET] Explanation of this action here. + Request ... + Response 200 Explanation of this response. + Headers ... + Body ... + Response 304 Explanation of this response. + Headers ... 

Please note that in the near future there will be fairly limited branching support to maintain content consistency.