为我们在Apiary.io中的每个响应指定描述 [英] Specify description for every response we have in Apiary.io

问题描述

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

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"

还有2个回复

+ Response 200 (application/xml)

    + Headers

            ETag: "Version2"

    + Body

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

+ Response 304 (application/xml)

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

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

有可能吗?

推荐答案

当前在API蓝图中无法表达这种逻辑.您始终可以在相应的响应中或在动作本身下口口相传"地描述它.例如:

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.

这篇关于为我们在Apiary.io中的每个响应指定描述的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！