Is it possible to nest NamedExamples?


#1

Hello,

We are building out an API which has a rather long and complicated JSON response body. During development of the API, as little things keep changing, it’s becoming tiresome to remember to keep editing and updating both the NamedExamples files, for the collection endpoints as well as the member endpoints.

Is it possible to nest the the NamedExamples inside of each other, where one is an array consisting on other NamedExample files?

When I have built the set up as described below, I get the following error in the main API RAML:

Null or undefined value is not allowed at  **examples/collection-sample.raml (3, 12)**
1. ↳ Error in the included file: Null or undefined value is not allowed at  **(9, 13)**
Null or undefined value is not allowed at  **examples/collection-sample.raml (5, 12)**
1. ↳ Error in the included file: Null or undefined value is not allowed at  **(9, 13)**

If this isn’t the correct way to build, I would appreciate it if you could point me in the right direction.

Many Thanks,


“api.raml”:

#%RAML 1.0 
......
......
/things:
  type: collection
  get: 
    responses:
      '200':
        body:
          application/json:
            example: !include examples/collection-sample.raml
  /{id}:
    type: member
      get:
        responses:
          '200':
            body:
              application/json:
                example: !include examples/member-a-sample.raml

“examples/member-a-sample.raml”:

#%RAML 1.0 NamedExample
uniqueRef: "FGJSDG834"
type: "A"
scheduled: "2018-12-30T10:15:00.000Z"
estimated: "2018-12-30T10:25:00.000Z"
actual: "2018-12-30T10:27:25.000Z"
......
......

“examples/member-a-sample.raml”:

#%RAML 1.0 NamedExample
uniqueRef: "F82KAPO45"
type: "B"
scheduled: "2018-11-30T10:15:00.000Z"
estimated: "2018-11-30T10:25:00.000Z"
actual: "2018-11-30T10:27:25.000Z"
......
......

“examples/collection-sample.raml”:

#%RAML 1.0 NamedExample
-
  !include: member-a-sample.raml
-
  !include: member-b-sample.raml

#2

Got it to work as I intended! The above setup works if I swap “example:” for “examples:” in the main RAML.

eg:

#%RAML 1.0 
......
......
/things:
  type: collection
  get: 
    responses:
      '200':
        body:
          application/json:
            examples: 
              a: !include examples/collection-sample.raml

#3

Great to hear that you made it work.

Note that your two #%RAML 1.0 NamedExample files above are NOT valid. Here’s how the RAML Spec describes the NamedExample fragment:

A declaration of the examples facet, whose key is a name of an example and whose value describes the example

Two ways you can go about fixing this: either add a <key>: at the root of your NamedExample files or remove the fragment identifier #%RAML 1.0 NamedExample.

PS: the fragment NamedExample is a bit misleading. It really should have been NamedExamples and we’ve already discussed renaming