RAML 1.0 — несколько примеров для одного ответа

Я не могу нигде найти код, демонстрирующий использование !include для нескольких примеров. Я пытаюсь сделать следующее:

200:
  description: Successful project creation
  body:
    application/json:
      type: JiraResponseSuccess
      example: !include examples/jira/projects/success/CreateSuccess.json
400:
  description: User error
  body:
    application/json:
      type: JiraResponseError
      examples:
        username: 
          !include examples/jira/projects/fail/user/UsernameFail.json
        projectKey: 
          !include examples/jira/projects/fail/user/ProjectKeyFail.json

Первый пример отображается нормально (где есть только один ответ), а второй - нет. синтаксис правильный, но я не понимаю, почему он задыхается от операторов !include. У меня какая-то ошибка или мне просто нужно подождать, пока инструмент наверстает упущенное?


syntax raml
person Wheeler    schedule 15.08.2016    source источник
comment
Похоже, множественные ответы просто еще не реализованы: github.com/raml-org/ raml-spec/issues/24   -  person Arne Burmeister    schedule 26.09.2016

Ответы (2)


arrow_upward
5
arrow_downward

Мы делаем то же самое для нашей документации RAML, плюс это решение также работает для RAML версии 0.8. У вас есть большая гибкость в том, как вы меняете тип контента, и вы даже можете включать пробелы и другие основные символы для удобства чтения.

Как заявил @manatico, типы контента не обязательно должны быть допустимым типом, поскольку RAML не проверяет его. Он просто признает, что есть разница, что позволяет привести несколько примеров. Для обеспечения ясности для клиентов я бы порекомендовал предварить фактический тип контента, но затем добавьте все, что соответствует вашим потребностям, для предоставления дополнительных примеров.

  get:
    responses:
      200:
        body:
          application/json - Example - Filtering by AppId:
             example: |
                { 
                   "tagId": "475889c9-773d-462a-a4ec-099242308170"
                   "appId": "12"
                   "tagName": "school",
                   "status": "ACTIVE"
                }
          application/json - Example - No Filtering:
             example: |
                {
                   "tagId": "58237aa0-3fa6-11e6-a16b-6d3f576c1098",
                   "tagName": "exercise",
                   "status": "ACTIVE"
                },
                {
                   "tagId": "06b8b7b5-8e6b-40e9-9e48-f87dec0665e4",
                   "tagName": "camping",
                   "status": "INACTIVE"
                }
person Michael M    schedule 03.10.2018

arrow_upward
3
arrow_downward

Вы можете указать разные типы контента для примеров основного ответа, даже если они на самом деле не являются реальными типами контента:

200:
  body:
    role/admin:
      example: !include http/list-res-200.json
    role/admin-Search-for-User:
      example: !include http/search-as-admin-res-200.json
    role/member-Search-for-User:
      example: !include http/search-as-member-res-200.json

Просто для того, чтобы документация работала нормально, я проанализировал HTML с помощью RAML2HTML, и все прошло без проблем.

person hestellezg    schedule 30.09.2016