How to write examples in external files


#1

I am trying to clean up my raml files and I would like to split my examples into a separate file(s) and include them. The spec says very little about doing examples and when it does it seems it only talks about yaml examples and not json.

Here is my current raml file and what I would like to know is how can I take the examples and split them out into separate file(s)?

#%RAML 1.0
---
title: Building
baseUri: http://api.example.com
version: v1
mediaType: application/ld+json
uses:
  Building: libraries/types/building/building.raml

    /building:
      get:
        description: Retrieve all buildings
        responses:
          200:
            body:
              application/ld+json:
                type: Building.Collection
                example: |
                  {
                    "@context":  [
                      "http://schema.org",
                      {
                        "example": "http://api.example.com/schema/"
                      }
                    ],
                    "type": "Collection",
                    "id": "http://api.example.com/building",
                    "member": [
                      {
                        "type": "Building",
                        "id": "http://api.example.com/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
                        "name": "Building1",
                        "availability": "http://api.example.com/booking/availability/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00"
                      },
                      {
                        "type": "Building",
                        "id": "http://api.example.com/building/id/4947df8-0e9e-4471-a2f9-9af509fb5889",
                        "name": "Building2",
                        "availability": "http://api.example.com/booking/availability/building/id/4947df8-0e9e-4471-a2f9-9af509fb5889"
                      },
                      {
                        "type": "Building",
                        "id": "http://api.example.com/building/id/45fd476-7e8a-2335-4637-45fd476f80bc",
                        "name": "Building3",
                        "availability": "http://api.example.com/booking/availability/building/id/45fd476-7e8a-2335-4637-45fd476f80bc"
                      }
                    ]
                  }

      /id/{buildingId}:
        uriParameters:
          buildingId:
            type: string
        get:
          description: Endpoint to handle requests for information about a building
          responses:
            200:
              body:
                application/ld+json:
                  type: Building.Full-LD
                  example: |
                    {
                      "@context": [
                        "http://schema.org",
                        {
                          "example": "http://api.example.com/schema/"
                        }
                      ],
                      "type": "Building",
                      "id": "http://api.example.com/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
                      "name": "Building1",
                      "availability": "http://api.example.com/booking/availability/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
                      "rooms" : "http://api.example.com/room/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00"
                    }

#2

You can do the following:

#%RAML 1.0
title: Building
baseUri: http://api.example.com
version: v1
mediaType: application/ld+json
uses:
  Building: libraries/types/building/building.raml

    /building:
      get:
        description: Retrieve all buildings
        responses:
          200:
            body:
              application/ld+json:
                type: Building.Collection
                example: !include json-example1.json
      /id/{buildingId}:
        uriParameters:
          buildingId:
            type: string
        get:
          description: Endpoint to handle requests for information about a building
          responses:
            200:
              body:
                application/ld+json:
                  type: Building.Full-LD
                  example: !include json-example2.json

json-example1.json

{
  "@context":  [
    "http://schema.org",
    {
      "example": "http://api.example.com/schema/"
    }
  ],
  "type": "Collection",
  "id": "http://api.example.com/building",
  "member": [
    {
      "type": "Building",
      "id": "http://api.example.com/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
      "name": "Building1",
      "availability": "http://api.example.com/booking/availability/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00"
    },
    {
      "type": "Building",
      "id": "http://api.example.com/building/id/4947df8-0e9e-4471-a2f9-9af509fb5889",
      "name": "Building2",
      "availability": "http://api.example.com/booking/availability/building/id/4947df8-0e9e-4471-a2f9-9af509fb5889"
    },
    {
      "type": "Building",
      "id": "http://api.example.com/building/id/45fd476-7e8a-2335-4637-45fd476f80bc",
      "name": "Building3",
      "availability": "http://api.example.com/booking/availability/building/id/45fd476-7e8a-2335-4637-45fd476f80bc"
    }
  ]
}

json-example2.json

{
  "@context": [
    "http://schema.org",
    {
      "example": "http://api.example.com/schema/"
    }
  ],
  "type": "Building",
  "id": "http://api.example.com/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
  "name": "Building1",
  "availability": "http://api.example.com/booking/availability/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00",
  "rooms" : "http://api.example.com/room/building/id/067e6162-3b6f-4ae2-a171-2470b63dff00"
}

Does that help?


#3

Ahh it seems the trick is it has to be named blah.json. We didn’t know the extension had to be exactly .json

Thank you


#4

I think the !include directive is YAML based and not a RAML thing, so using it to include any file type would require the extension of the file type to be provided.


#5

We had an extension it just was .jsonld so we had to change it to .json


#6

I think you can even use jsonld as the extension. Shouldn’t be really problematic, I think.