What is the structure to declare examples in their own raml file?


#1

Namely, how do I get

#%RAML 1.0 NamedExample

to work properly? I can’t find any examples anywhere. Not the RAML repositories, not in the forums, or even in the RAML documentation.
Assuming I have a RAML library filled with types and one of the types is something like:

   avatar:
     type: array
     required: false
     items:
       type: object
       required: true
       properties:
         size:
           type: string
           required: true
         url:
           type: string
           required: true

so avatar example would be something like:

     AvatarExample:
         -
           size: "Big"
           url: "Example1.com"
         -
           size: "Small"
           url: "Example2.com"

How can I create my own RAML NamedExamples file, write the example into it and then call it from another file like “api.raml” or something?

   #import goes here <----------------------------??????????????
     /avatar:
       get:
         description: Just an avatar.
         responses:
           200:
             body:
               application/json:
                 type: avatar.avatar
                 example: <---------------------????????????????

While I can use a JSON file for the examples and that will work, I’d rather use a namedExamples raml file to contain all of the examples in one place.

Thanks for the help!


#2

Hi rickyd,
I know this is an old discussion but, since I have not seen a concrete example, I have decided to bring it back to life because it could be useful for someone else.
In your example the NamedExample.raml will be:

#%RAML 1.0 NamedExample

AvatarExample:
         - size: "Big"
           url: "Example1.com"
         - size: "Small"
           url: "Example2.com"

And your api.raml will use it in the following way:

/avatar:
       get:
         description: Just an avatar.
         responses:
           200:
             body:
               application/json:
                 example: !include path/to/the/named/example/NamedExample.raml

I removed the avatar type since it should be a resourceTypes instead.


#3

You cannot reference #%RAML 1.0 NamedExample fragments like that. That’s because as the Spec says, this type of fragment is for “A declaration of the examples facet”[1]. That’s “examples” with a trailing “s” (plural) as opposed to “example” (singular).

You can either reference that same fragment using examples: instead of example: or alter your example so it is a “non-typed” fragment, e.g.

# no RAML fragment identifier here
- size: "Big"
  url: "Example1.com"
- size: "Small"
  url: "Example2.com"

[1] https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#typed-fragments