3

I have docs, and try to add new API's docs to that docs.

I gone through basic RAML docs.

I have raml file as.

#Filename: base.raml
title: Test RAML
documentation:
  - title: Test RAML docs first time :)
    content: This is RAML testing
baseUri: https://myportal.com/{version}/scriptmanagement
version: v1.0
mediaType: application/json
protocols: [ HTTPS ]

/test:
    !include raml/test.raml

And the actual raml content is in test.raml

#Filename: test.raml
displayName: Test RAML Inheritance
description: Testing for RAML inheritance for responses.

get:
    description: Get all TEST
    headers:
        name:
            description: name required in each request
            example: testname
            required: true
    responses:
        200:
            description: SUCCESS
            body:
                application/json:
                    example: |
                        {}
        400:
            description: BAD REQUEST
            body:
                application/json:
                    example: |
                        {"error": "Bad Request"}
        500:
            description: INTERNAL ERROR
            body:
                application/json:
                    example: |
                        {"error": "Internal Error"}

post:
    description: Get all TEST
    headers:
        name:
            description: name required in each request
            example: testname
            required: true
    responses:
        200:
            description: SUCCESS
            body:
                application/json:
                    example: |
                        {"message": "Created"}
        400:
            description: BAD REQUEST
            body:
                application/json:
                    example: |
                       {"error": "Bad Request"}
        500:
            description: INTERNAL ERROR
            body:
                application/json:
                    example: |
                        {"error": "Internal Error"}


/{test_id}:
    description: TEST DETAILS
    get:
        description: Retrieve resource own by x-user-name
        headers:
            name:
                description: name required in each request
                example: testname
                required: true
        responses:
            200:
                description: SUCCESS
                body:
                    application/json:
                        example: |
                            {"message": "Details"}
            400:
                description: BAD REQUEST
                body:
                    application/json:
                        example: |
                            {"error": "Bad Request"}
            500:
                description: INTERNAL ERROR
                body:
                    application/json:
                        example: |
                            {"error": "Internal Error"}

In above RAML, 400 and 500 response is common, and name headers is common.

How can I write this once and add to all resources? I tried traits and <<: both not works.

Nilesh
  • 20,521
  • 16
  • 92
  • 148

1 Answers1

4

Traits are the right solution here. This is an example for your name header scenario:

Define the trait

traits:
  nameHeader:
    headers:
      name:
        description: name required in each request
        example: testname
        required: true

Use the trait

To use this trait you have to explicitly mention it inside your request specification:

/{test_id}:
  description: TEST DETAILS
  get:
    description: Retrieve resource own by x-user-name
    is: [nameHeader]
    responses:
      200:
        description: SUCCESS
        body:
          application/json:
            example: |
              {"message": "Details"}

The same way you can define traits for your responses.

flogy
  • 906
  • 4
  • 16