Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Dynamic population of example json in RAML

Tags:

raml

I am loving how RAML can dynamically reference different schemas when declaring a resourceType like:

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
      post:
        body:
          application/json:
            schema: <<schema>>Create
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>

Here I am able to use this like

/users:
  type: { collection: { schema: user } }

and RAML will give me user schema responses from GETs and POSTs and also use the userCreate schema for sending POST requests. Cool! Now I can reuse my collection definition with tons of different schemas.

But now that I want to have example json for everything too, I was hoping to utilize the <<schema>> var in another way to leverage "code reuse". I was hoping to be able to do

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json
      post:
        body:
          application/json:
            schema: <<schema>>Create
            example: examples/v1-<<schema>>-create.json
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json

but unfortunately this does not work. I get an error saying

error: File with path "/examples/v1-%3C%3Cschema%3E%3E.json" does not exist

So now I have resorted to manually adding this to all my collections and the /users example above has become

/users:
  type: { collection: { schema: user } }
  get:
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json
  post:
    body:
      application/json:
        example: !include examples/v1-user-create.json
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json

To me, this is a LOT of overhead just to add examples. Especially when I want to repeat the pattern over many resources.

The question: Is there a way to accomplish this?

like image 350
Eric Olson Avatar asked Dec 10 '14 17:12

Eric Olson


People also ask

Where can I find Raml examples?

GitHub - raml-org/raml-examples: This repository contains valid RAML 1.0 examples. These examples are not only part of the spec, but also represent RAML features in different scenarios. Failed to load latest commit information. This repository contains valid RAML examples.

Is there a way to define resources in Raml?

#%RAML 1.0 title: /resources: get: post: / {resourceId}: get: put: delete: So, we found two different type of resources. The item (represented by an id), and the collection (containing all the items). It would be nice to be able to define these types, and declare the resources of those types. Luckily, there is a way to do this in RAML.

What is Raml modeling?

Model your endpoints with access information, HTTP verbs, parameters, example responses and more RAML lets you see what your API looks like as you design it, using easy to read plain text.

How do I reference a namedexample Raml file?

Reference a NamedExample RAML file which defined the example in RAML format. You must use the examples (plural) keyword and can provide one or multiple examples. See line 22 in the example below. Using the example (singular) keyword followed by a text message.


1 Answers

No, this is not allowed in RAML 0.8 according to the spec. It might be allowed in future versions though.

like image 159
Robin Green Avatar answered Nov 03 '22 10:11

Robin Green