Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

RAML 1.0 - Multiple Examples for a Single Response

Tags:

syntax

raml

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?

like image 577
Wheeler Avatar asked Aug 15 '16 21:08

Wheeler


People also ask

What is the difference between traits and ResourceType in RAML?

Whereas a resource type is used to extract patterns from resource definitions, a trait is used to extract patterns from method definitions that are common across resources.

How do I apply a security schema in RAML?

To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the securedBy attribute. The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the securitySchemes property of RAML document root.

How do you write data types in RAML?

You can define a type at the beginning of your RAML file, and you can later reference that same type to describe the body of as many API requests or responses as you need. You can even define a data type to inherit properties of another type within your API.


1 Answers

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"
                }
like image 118
Michael M Avatar answered Sep 19 '22 13:09

Michael M