Add fields to doc and resources


#1

I’m still newish to RAML so pardon if this is obvious. I just went through the spec but didn’t find anything.

I want to add a couple fields to the root-level doc and to resources that I am going to use purely for server implementation purposes. So, I’d like something like this:

#%RAML 1.0
title: Foo
description: Bar
myField:
baz: 123
/test:
myResourceField: abc

So, really, just want to add some things that will validate, but otherwise be ignored except by my tooling.


#2

Not entirely clear on what you are asking, but I would guess that annotations may allow you to achieve what it is I think you are asking for. You can then use the parser to look for your specific defined annotations that you would document on how to use them. Hence, your customer generator using the RAML 1.0 parser to consumer RAML with your annotations in it.


#3

Is there an example of annotations usage? I can’t seem to find one.

I just want the ability to add arbitrary objects into the tree…


#4

Here you go:

#%RAML 1.0
title: My API

annotationTypes:
  info:
    properties:
      author: string
      lincense: string
types:
  User: !include user.raml

/users:
  get:
    (info):
      author: Christian
      lincense: MIT
    responses:
      200:
        body:
          application/json:
            type: User[]

#5

Thanks Christian - that is perfect for what I need!

Is that only in RAML 1.0?

Also, do you know if its possible to do anything similar at the root level (the level of title)? To get something like this:

#%RAML 1.0
title: My Api
(myProperty):  
  key: value

#6

Yes annotations has been introduced in RAML 1.0 RC1, and yes you can also have annotation at the root-level of your API.


#7

How would the root-level annotation look?


#8

You’ve done that already in your latest post :wink: But here a modified example:

#%RAML 1.0
title: My API

annotationTypes:
  info:
    properties:
      author: string
      lincense: string
types:
  User: !include user.raml

(info):
   author: Christian
   lincense: MIT

/users:
  get:
    responses:
      200:
        body:
          application/json:
            type: User[]

#9

Hey Christian - is it legal to have multiple entries in a single file?

Like so:

---
title: foo
<other info>

---
title: bar
<info for second entry>

All in a single file?


#10

As far as I know, no this is not legal in a raml file. You could modularize them with RAML 1.0 though I believe. Why would you want to put multiple in one file? It seems each of these would be separate API surfaces? Otherwise, you would use the Description tags and/or include markdown or external documentation to help keep the RAML file size down.


#11

As @Kevin_Duffey perfectly highlights. YAML keys (title is a key) are usually unique on purpose. A RAML file represents one API which has only one specific title and so on. What is your use case?