Guide to Defining Examples in RAML 1.0
When defining examples in external files for a type, trait, or resource type in your RAML 1.0 API specification, follow these rules:
-
For a single example, either use the
examplefacet and include a .yaml file or use theexamplesfacet and include a .raml NamedExample fragment file. -
For multiple examples, always use the
examplesfacet and either:-
Define multiple examples, each pointing to individual .yaml files, with a single example per file
-
Include a .raml file containing two or more examples defined in a single NamedExample fragment
-
Using a Single Example That Is in a .yaml File
In your specification, include the file with an example facet. In your .yaml file, ensure that the example is at the root level.
The files api.raml and fragment.yaml illustrate the correct way to use a single example that is in a .yaml file:
#%RAML 1.0
title: test
types:
A:
properties:
givenName: string
familyName: string
example: !include fragment.yaml
givenName: ”Chiaki” familyName: "Mukai"
Using a Single Example That Is in a .raml NamedExample Fragment File
In your specification, include the file with an example facet. In your NamedExample fragment, ensure that the example is not at the root level of the file. The fragment must contain a key that is the name of the example.
The files api.raml and fragment.raml illustrate the correct way to use a single example that is in a .raml file:
#%RAML 1.0
title: test
types:
A:
properties:
givenName: string
familyName: string
examples: !include fragment.raml
#%RAML 1.0 NamedExample fullName: givenName: ”Chiaki” familyName: "Mukai"
Do not use a fragment that looks like this:
#%RAML 1.0 NamedExample givenName: ”Chiaki” familyName: "Mukai"
In this case, API Designer ignores the header and uses the example. However, if you validate a specification with any other RAML processors, NamedExample fragments that define only one example should generate errors, in accordance with the RAML 1.0 specification.
Naming Two Examples That Are in .yaml Files
In your specification, include the file with the examples facet and name each example. In your .yaml files, ensure that each example is at the root level.
The files api.raml, fragment1.yaml, and fragment2.yaml illustrate the correct way to use two examples that are in .yaml files:
#%RAML 1.0
title: test
types:
A:
properties:
givenName: string
familyName: string
examples:
fullName: !include fragment1.yaml
otherFullName: !include fragment2.yaml
givenName: ”Chiaki” familyName: "Mukai"
givenName: "Kyung-won" familyName: "Park"
Naming Two Examples That Are in a NamedExample Fragment
In your specification, include the file with an examples facet. In your NamedExample fragment, ensure that neither example is at the root level of the file. The fragment must contain two keys that are each the name of an example.
The files api.raml, and fragment.raml illustrate the correct way to use a two examples that are in a .raml file:
#%RAML 1.0
title: test
types:
A:
properties:
givenName: string
familyName: string
examples: !include fragment.raml
#%RAML 1.0 NamedExample fullName: givenName: ”Chiaki” familyName: "Mukai" otherFullName: givenName: "Kyung-won" familyName: "Park"