Generic response structure in RAML not working

Question

I'm using Mule 4 and Anypoint Studio 7.

I'm defining and API with a common response structure because I want to use it with all examples I have, but is not working fine.

Example of two possible responses with the common structure:

Response with Employee Data:

{
   "pagination": { "firstPage": 1, "numRows": 10 },
   "data": { "employeeId": 1, "employeeName": "Alex" },
   "success": true
}

Response with Employee Task:

{
   "pagination": { "firstPage": 1, "numRows": 10 },
   "data": { "employeeId": 1, "employeeTask": "Clean the appartment" },
   "success": true
}

I'm trying to define the response structure with a trait:

responseMessage:
    responses: 
      200:
        body: 
          application/json:
            example: |
              { "pagination": {"firstPage": 1, "numRows": 10}, "data": <<exampleName>>, "succes": true }

And finally, define the method:

/employees:
  get:
    type:
      exampleReference1: |
          {"SongID":1,"SongName":"London Dreams","Singer":"David"}
    is: [responseMessage: { typeName: exampleReference1 }]

I'm getting "null" in "data" when I try "mock" service:

  "pagination": {
    "firstPage": 1,
    "numRows": 10
  },
  "data": null,
  "succes": true
}

Answer 1

You cannot use "<<reference>>" inside a file because RAML treats everything as a String.

Take a look here and modify the code according to your use case.

https://raml.org/developers/raml-200-tutorial#parameters

Answer 2

finally I get an approach. I don't know if is the best way to do it. If anyone can give me their opinion would be great!!

Trait:

traits:
  responseMessage: 
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              _metadata:
                type: Metadata
              data:
                type: <<typeName>>
              success: boolean

Types

types:
  Metadata: 
    type: object
        properties:
          firstPage:
            type: integer
            description: First Page.
            required: true
            example: 1
          numRows:
            type: integer
            description: Results x page.
            required: true
            example: 10
          nextPage:
            type: string
            description: Link to next page.
            required: true
            example: "https://api.example.com/apiname/v1/apimethod?firstPage=3&offset=10"
  Employee: 
    type: object
        properties:
          id:
            type: integer
            description: Employee id.
            required: true
            example: 1234
          employeeName:
            type: string
            description: Employee name.
            required: true
            example: "Joseph"
  Task: 
    type: object
        properties:
          id:
            type: integer
            description: Task id.
            required: true
            example: 9876
          employeeTask:
            type: string
            description: Task name.
            required: true
            example: "Clean the appartment"

Methods

/employee:
  /{id}:
    get:
      is: [responseMessage: {typeName: Employee}]
      
/task:
  /{id}:
    get:
      is: [responseMessage: {typeName: Task}]

And this is how it see in documentation pane:

EMPLOYEE

{
  "_metadata": {
    "firstPage": 1,
    "numRows": 10,
    "nextPage": "https://api.example.com/apiname/v1/apimethod?firstPage=3&offset=10"
  },
  "data": {
    "id": 1234,
    "employeeName": "Joseph"
  },
  "success": false
}

TASK

{
  "_metadata": {
    "firstPage": 1,
    "numRows": 10,
    "nextPage": "https://api.example.com/apiname/v1/apimethod?firstPage=3&offset=10"
  },
  "data": {
    "id": 1234,
    "employeeTask": "Clean the appartment"
  },
  "success": false
}

Is this a good way o maybe I must define an example?