Укажите описание каждого ответа, который у нас есть в 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. Вы всегда можете описать его «в рот» в соответствующих ответах или под действием самого действия. Например:

# 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 

      ... 

Примечание, вполне вероятно, будет некоторое ограниченное ветвление поддержку в ближайшем будущем, с тем чтобы поддержать согласование содержания.