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?
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.
#%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.
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.
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.
No, this is not allowed in RAML 0.8 according to the spec. It might be allowed in future versions though.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With