Adding Examples to the API Spec | MuleSoft Documentation
# Adding Examples to the API Spec
Cloud IDE 
Desktop IDE 
**Open Beta Release** : The **cloud IDE is in open beta**. Any use of Anypoint Code Builder in its beta state is subject to the applicable beta services terms and conditions, available from the IDE.
Add API fragments from Exchange for a data type and examples to the American Flights API specification. Then create your own examples for the specification, and add a custom message for a response.
## Before You Begin
Complete all the procedures in Designing the American Flights API Spec.
## Add Fragments from Exchange to Your Project
Add fragments to the project directory so that you can include them in your specification.
  * **Training: American Flight Data Type** fragment for an object that corresponds to the definition of a flight
  * **Training: American Flights Example** fragment for data that the API returns


To add the fragments:
  1. In Anypoint Code Builder, open your American Flights API specification, `american-flights-api.raml`.
  2. Open the Command Palette.
Show me how
     * Use the keyboard shortcuts:
       * Mac: Cmd+Shift+p
       * Windows: Ctrl+Shift+p
     * In the desktop IDE, select **View** > **Command Palette**.
     * In the cloud IDE, click the (menu) icon, and select **View** > **Command Palette**.
  3. Provide this command:
```
MuleSoft: Add fragment dependency from Exchange
```

  4. If prompted, log in to Anypoint Platform so that you can download an asset.
  5. In the **Search for Asset** field, provide the name of the data type asset to add:
```
Training: American Flight Data Type
```

  6. Select the asset from the **Assets From Exchange** menu.
  7. Select the latest version of the asset, such as **v1.0.1**.
The IDE adds the fragment as a dependency. When the process is complete, check for the `AmericanFlightDataType.raml` asset **Project Dependencies** area of the Explorer, for example:
The dependency is also listed in the `exchange.json` file for the project, in your project directory from the Explorer.
  8. From the Command Palette, add another fragment:
```
MuleSoft: Add fragment dependency from Exchange
```

  9. Provide the name of the asset to add:
```
Training: American Flights Example
```

  10. Select the latest version of the **American Flights Example** asset.
The IDE adds the fragment as a dependency to **Project Dependencies** and `exchange.json`.
  11. Proceed to Include the Fragments in the Specification.


## Include the Fragments in the Specification
Use `!include` directives to add the fragments to the specification:
  * The `AmericanFlight` data type is defined in `AmericanFlightDataType.raml`.
  * The `AmericanFlightsExample.raml` example is for a `200` response to the `get` request.


To include the fragments:
  1. Open **american-flight-api.raml** from the project directory in Explorer.
  2. Replace the existing content with this:
```
#%RAML 1.0
title: American Flights API
types: **(1)**
 AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml
/flights:
 get:
  queryParameters:
   destination:
    required: false
    enum:
     - SFO
     - LAX
     - CLE
  responses:
   200:
    body:
     application/json: **(2)**
      type: AmericanFlight[]
      examples: **(3)**
       output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml
 post:
 /{ID}:
  get:
```

Uses `!include` to add the `AmericanFlight` object from `AmericanFlightDataType.raml` as a data type  Note that you can use built-in functionality to insert the `!include` directive and file path from the specification file, for example:
    1. After typing `AmericanFlight: ` (with a space at the end), click Ctrl+Spacebar, start typing `!include`, and select `!include` from the drop-down menu in the RAML file, for example:
    2. Follow the same process to add the example, selecting `exchange_modules` directory and progressing step-by-step to `AmericanFlightsDataType.raml`, for example:  
---  
Sets the format of the body of the response to JSON (`application/json`) and configures the type of the response as an array of `AmericanFlight` objects (`AmericanFlight[]`)  
Adds the `AmericanFlightsExample.raml` example  
  3. Proceed to Create and Include an Example for a Get Request by Flight ID.


## Create and Include an Example for a Get Request by Flight ID
Create an example for the post response, and include it in the specification.
  1. In the Explorer, right-click on an empty space, and create a folder named `examples`.
  2. Right-click your `examples` folder, and create a new file named `AmericanFlightExample.raml`.
  3. In the open file, add this example:
```
#%RAML 1.0 NamedExample
value:
  ID: 1
  code: ER38sd
  price: 400
  departureDate: 2017/07/26
  origin: CLE
  destination: SFO
  emptySeats: 0
  plane:
   type: Boeing 737
   totalSeats: 150
```

  4. Return to your `american-flights-api.raml` file, and create a set of elements under `/{ID}/get` for responses:
```
#%RAML 1.0
title: American Flights API
types:
 AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml
/flights:
 get:
  queryParameters:
   destination:
    required: false
    enum:
     - SFO
     - LAX
     - CLE
  responses:
   200:
    body:
     application/json:
      type: AmericanFlight[]
 post:
 /{ID}:
  get:
   responses: **(1)**
    200:
     body: **(2)**
      application/json:
       type: AmericanFlight
       examples: **(3)**
        output: !include examples/AmericanFlightExample.raml
```

Adds a response with a `200` code  
---  
Specifies the JSON format and type (`AmericanFlight`) of the **get** request body  
Adds your example from the `/examples` directory as the content for the body of the request  
  5. Proceed to Configure an Example for the Post Method.


## Configure an Example for the Post Method
Define an example for the `post` request:
  1. Specify that a request to the `/flights:post` method requires an object of the `AmericanFlight` type:
```
#%RAML 1.0
title: American Flights API
types:
 AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml
/flights:
 get:
  queryParameters:
   destination:
    required: false
    enum:
     - SFO
     - LAX
     - CLE
  responses:
   200:
    body:
     application/json:
      type: AmericanFlight[]
 post:
  body: **(1)**
   application/json:
    type: AmericanFlight **(2)**
 /{ID}:
  get:
   responses:
    200:
     body:
      application/json:
       type: AmericanFlight
       examples:
        output: !include examples/AmericanFlightExample.raml
```

Specifies a JSON-formatted body for the `post` method  
---  
Configures `AmericanFlight` as the type for the `post` method  
  2. Under your `/examples` folder, create a file named `AmericanFlightNoIDExample.raml`, and copy this example to the file:
```
#%RAML 1.0 NamedExample
value:
  code: ER38sd
  price: 400
  departureDate: 2017/07/26
  origin: CLE
  destination: SFO
  emptySeats: 0
  plane:
   type: Boeing 737
   totalSeats: 150
```
Specifies a JSON-formatted body for the `post` method  
---  
Configures `AmericanFlight` as the type for the `post` method  
  2. Under your `/examples` folder, create a file named `AmericanFlightNoIDExample.raml`, and copy this example to the file:
```
#%RAML 1.0 NamedExample
value:
  code: ER38sd
  price: 400
  departureDate: 2017/07/26
  origin: CLE
  destination: SFO
  emptySeats: 0
  plane:
   type: Boeing 737
   totalSeats: 150
```

To simulate a new flight record, this example does not provide an `ID` parameter.
  3. In the `american-flights-api.raml` file, add the example as a response to the `post` method, and include a custom message.
Notice the `!include` directive at number 5:
```
#%RAML 1.0
title: American Flights API
types:
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml
/flights:
 get:
  queryParameters: **(1)**
   destination:
    required: false
    enum:
     - SFO
     - LAX
     - CLE
  responses: **(2)**
   200:
    body:
     application/json:
      type: AmericanFlight[]
      examples:
       output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml
 post:
  body:
   application/json:
    type: AmericanFlight
    examples: **(3)**
     input: !include examples/AmericanFlightNoIDExample.raml
  responses:
   201:
    body:
     application/json: **(4)**
      example:
       message: Flight added (but not really)
 /{ID}:
  get:
   responses:
    200:
     body:
      application/json: **(5)**
       type: AmericanFlight
       examples:
        output: !include examples/AmericanFlightExample.raml
```

Select a destination.  
---  
Return an array of `AmericanFlight` objects for that destination.  
Post an `AmericanFlight` object from an `examples/AmericanFlightNoIDExample.raml`.  
Provide a custom message for a response in JSON format to the `post` method  
Add your example from `examples/AmericanFlightExample.raml` as a response to the nested `get` request  
  4. Proceed to Testing the API Spec with the Mocking Service to test the API endpoints.