7

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?

Almad
  • 5,753
  • 7
  • 35
  • 53
Dmitrii Lobanov
  • 4,897
  • 1
  • 33
  • 50

1 Answers1

8

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.

Zdenek
  • 3,653
  • 27
  • 34
  • no, it doesn't work :( It doesn't show the description for the particular response. – Dmitrii Lobanov Oct 31 '13 at 08:03
  • 1
    @DmitryLobanov The fact it is not displayed in rendered Apiary documentation is an actual [bug in Apiary](http://support.apiary.io/forums/120125-general/suggestions/4811560-allow-to-describe-a-response-in-plain-markdown). The format and parser itself will handle it correctly. Sorry about the confusion. – Zdenek Nov 02 '13 at 03:34
  • Just a note - this should now display correctly in Apiary's new documentation - http://blog.apiary.io/2014/03/20/Re-API-Design-for-Humans/ – Zdenek May 20 '14 at 21:09