Is it possible to specify description for every response to some request? Suppose, we have a request
### Retrieve resource [GET]
+ Headers
If-None-Match: "Version1"
And 2 responses
+ Response 200 (application/xml)
+ Headers
ETag: "Version2"
+ Body
<Xml>
<A>
<B />
<C />
</A>
</Xml>
+ Response 304 (application/xml)
What I would like is to specify description like here (please note comments right under + 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?
Currently there is not way to express such a logic in the API Blueprint. You can always describe it "by mouth" in the respective responses or under 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
...
Note it is quite likely there will be some limited branching support in the near future in order to support content negotiation.