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?
To use Apiary to design APIs, click 'Apiary'. Use your GitHub account to start API design. Once logged in, the UI gives an option to create a new API. Specify a name and click the “Create API” button.
API Blueprint is a high-level language for describing web APIs. The syntax is a combination of Markdown syntax and Markdown Syntax for Object Notation (MSON), and the files are saved with a . apib extension.
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With