RAML 1.0 - 单个响应的多个示例

Question

我无法在任何地方找到任何代码来演示!include对多个示例使用 a 。我正在尝试以下操作：

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语句。我有错误还是我只需要等待工具赶上？

Answer 1

我们一直在为我们的 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"
                }

Answer 2

您可以为正文响应示例指定不同的内容类型，即使它们实际上不是真正的内容类型：

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

只是为了文档工作正常，我用RAML2HTML解析为 HTML ，一切都没有问题。