How to specify examples in RAML 1.0 API Specification

What is the difference between an example and examples in RAML 1.0?

When specifying examples in external files for a type, trait, or resource type in your RAML 1.0 API specification, use these steps:

1. To define a single example:

• • • 
      
      • Use the example facet and include a .yaml file
    
    

    #%RAML 1.0
    title: Using example
    types:
      A:
        properties:
          firstName: string
          lastName: string
        example: !include myFragment.yaml

    
    
    
    
    • 
      
      
      
      • Use the examples facet and include a .raml NamedExample fragment file.
    
    
    
    

    #%RAML 1.0
    title: Using example
    types:
      A:
        properties:
          firstName: string
          lastName: string
        examples: !include myFragment.raml

    
    

How to specify examples in RAML 1.0 API Specification

2. For multiple examples, always use the examples facet and either:

• Define multiple examples, each referring to individual .yaml files, with a single example per file

#%RAML 1.0
title: Using examples in RAML
types:
  A:
    properties:
      firstName: string
      lastName: string
    examples:
      Names: !include naming.yaml
      address: !include address.yaml

• 
  
  
  
  • Include a .raml file containing two or more examples defined in a same single example fragment
  
  

#%RAML 1.0
title: Using example
types:
  A:
    properties:
      firstName: string
      lastName: string
    examples: !include allFragmentInfo.raml

Summary:

The key takeaway from this article is to define example for including a single example with .yaml file and for remaining scenarios, we have to define as examples