rest - 为我们在 Apiary.io 中的每个响应指定描述

Question

是否可以为某个请求的每个响应指定描述？假设，我们有一个请求

### Retrieve resource [GET]

    + Headers

            If-None-Match: "Version1"

和 2 个回复

+ Response 200 (application/xml)

    + Headers

            ETag: "Version2"

    + Body

            <Xml>
                <A>
                    <B />
                    <C />
                </A>
            </Xml>

+ Response 304 (application/xml)

我想要的是在此处指定描述(请注意 + Response 行下的注释):

+ 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

是否可以？

Answer 1

目前没有办法在 API Blueprint 中表达这样的逻辑。您始终可以在相应的响应中或在 Action 本身下“通过口”来描述它。例如:

# 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

            ...

请注意，为了支持内容协商，在不久的将来很可能会有一些有限的分支支持。