Search code examples
apiraml

either/or body properties and multiple examples

I am new to RAML and recently inherited a project I need to update to reflect new specifications.

This is a fairly simple RAML document, all I am doing is adding a new body property, and I would like to show multiple examples.

Previously, there was a "codeType1" property, which was required for the post.

Now, there is a new "codeType2" property, and one of the two is required. So either codeType1, or codeType2 must be in the post body. I don't know how to express that requirement in RAML.

Also I would like to have two examples, for each of the scenarios.

I was able to add the new codeType, but I don't know how to express the validation rule.

This is what I have currently:

#%RAML 1.0
title: Auth Service
version: v1
protocols: [HTTPS]
mediaType: application/json

/auth:
    post:
      description: Authenticate a client to the API.
      body:
        application/json:
          properties:
            {
            "codeType1": {
                type: string,
                required: true
              },
            "codeType2":{
                type: string,
                required: true
              },
            "userId":{
                type: string,
                required: true
              },
            "password":{
                type: string,
                required: true
              },
            }
          example:
            {
              "codeType1":"994056",
              "codeType2":"##0023",
              "userId":"[email protected]",
              "password":"Abc123!",
            }
      responses:
        200:
          description: Successful authentication.
          body:
            application/json:
              example:
                {
                  "status": "success",
                  "message": "Authentication success",
                  "data": {
                    "token": "SDKFHDSLFDJSFDKJFDHSFLJKFHLSKFSFLKFLSDFJHSLHFSDF"
                  }
                }
Solution

  • Try this:

    #%RAML 1.0
title: Auth Service
version: v1
protocols: [HTTPS]
mediaType: application/json

types:
  UserCred:
    properties:
      userId:
      password:
  Type1:
    type: UserCred
    properties:
      codeType1:
  Type2:
    type: UserCred
    properties:
      codeType2:

/auth:
    post:
      description: Authenticate a client to the API.
      body:
        application/json:
          type: Type1 | Type2
          examples:
            ex1: 
              codeType1: "994056"
              userId: "[email protected]"
              password : "Abc123!"
            ex2:
              codeType2: "12345"
              userId: "[email protected]"
              password: "ZYX098"

    I only copied the parts I changed.

    Here's a couple of references from the RAML 1.0 spec that I made use above: