Menu
I am unable to find any code anywhere that demonstrates using a !include for multiple examples. I'm trying to attempt the following:
200:
description: Successful project creation
body:
application/json:
type: JiraResponseSuccess
example: !include examples/jira/projects/success/CreateSuccess.json
400:
description: User error
body:
application/json:
type: JiraResponseError
examples:
username:
!include examples/jira/projects/fail/user/UsernameFail.json
projectKey:
!include examples/jira/projects/fail/user/ProjectKeyFail.json
The first example renders fine (where there's only a single response) whereas the second does not. The syntax is correct, but I don't understand why it's choking on the !include statements. Do I have an error or do I just need to wait for the tooling to catch up?
577
Whereas a resource type is used to extract patterns from resource definitions, a trait is used to extract patterns from method definitions that are common across resources.
To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the securedBy attribute. The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the securitySchemes property of RAML document root.
You can define a type at the beginning of your RAML file, and you can later reference that same type to describe the body of as many API requests or responses as you need. You can even define a data type to inherit properties of another type within your API.
We have been doing the same thing for our RAML documentation, plus this solution also works for RAML version 0.8. You have a lot of flexibility with how you change the content type, and you can even include spaces and other basic symbols for readability.
As @manatico stated, the content types do not have to be a valid type, as RAML doesn't validate it. It just recognizes that there is a difference, which allows multiple examples to be listed. For providing clarity to customers, I would recommend prefacing the actual content type, but follow it with whatever suits your needs for providing additional examples.
get:
responses:
200:
body:
application/json - Example - Filtering by AppId:
example: |
{
"tagId": "475889c9-773d-462a-a4ec-099242308170"
"appId": "12"
"tagName": "school",
"status": "ACTIVE"
}
application/json - Example - No Filtering:
example: |
{
"tagId": "58237aa0-3fa6-11e6-a16b-6d3f576c1098",
"tagName": "exercise",
"status": "ACTIVE"
},
{
"tagId": "06b8b7b5-8e6b-40e9-9e48-f87dec0665e4",
"tagName": "camping",
"status": "INACTIVE"
}
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
