RAML 1.0 - Multiple Examples for a Single Response

Question

I am unable to find any code anywhere that demonstrates using a !include for multiple examples. I'm trying to attempt the following:

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

The first example renders fine (where there's only a single response) whereas the second does not. The syntax is correct, but I don't understand why it's choking on the !include statements. Do I have an error or do I just need to wait for the tooling to catch up?

Mazzard

Look like multiple responses are simply not implemented yet: github.com/raml-org/raml-spec/issues/24 – Topi

It's added in recent raml and works for me the above way. – Fore

Answer 1

We have been doing the same thing for our RAML documentation, plus this solution also works for RAML version 0.8. You have a lot of flexibility with how you change the content type, and you can even include spaces and other basic symbols for readability.

As @manatico stated, the content types do not have to be a valid type, as RAML doesn't validate it. It just recognizes that there is a difference, which allows multiple examples to be listed. For providing clarity to customers, I would recommend prefacing the actual content type, but follow it with whatever suits your needs for providing additional examples.

  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"
                }

Noontide

Answer 2

You can specify different content types for the body response examples, even if they aren't actually real content types:

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

Just for documentation works fine, I parsed to HTML with RAML2HTML and all went without problem.

Plotinus