Skip to content

Commit ff56088

Browse files
author
Eugen
committed
Merge pull request eugenp#358 from KevinGilmore/master
RAML Annotations article
2 parents ac38b95 + 3fcfc67 commit ff56088

File tree

13 files changed

+330
-0
lines changed

13 files changed

+330
-0
lines changed

‎raml/annotations/api.raml‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
#%RAML 1.0
2+
title: API for REST Services used in the RAML tutorials on Baeldung.com
3+
documentation:
4+
- title: Overview
5+
content: |
6+
This document defines the interface for the REST services
7+
used in the popular RAML Tutorial series at Baeldung.com.
8+
- title: Disclaimer
9+
content: |
10+
All names used in this definition are purely fictional.
11+
Any similarities between the names used in this tutorial and those of real persons, whether living or dead, are merely coincidental.
12+
- title: Copyright
13+
content: Copyright 2016 by Baeldung.com. All rights reserved.
14+
uses:
15+
mySecuritySchemes: !include libraries/securitySchemes.raml
16+
myDataTypes: !include libraries/dataTypes.raml
17+
myTraits: !include libraries/traits.raml
18+
myResourceTypes: !include libraries/resourceTypes.raml
19+
version: v1
20+
protocols: [ HTTPS ]
21+
baseUri: http://rest-api.baeldung.com/api/{version}
22+
mediaType: application/json
23+
securedBy: [ mySecuritySchemes.basicAuth ]
24+
annotationTypes:
25+
testCase:
26+
allowedTargets: [ Method ]
27+
allowMultiple: true
28+
usage: |
29+
Use this annotation to declare a test case
30+
within a testSuite declaration.
31+
You may apply this annotation multiple times
32+
within the target testSuite.
33+
properties:
34+
scenario: string
35+
setupScript?: string[]
36+
testScript: string[]
37+
expectedOutput?: string
38+
cleanupScript?: string[]
39+
/foos:
40+
type: myResourceTypes.collection
41+
get:
42+
queryParameters:
43+
name?: string
44+
ownerName?: string
45+
responses:
46+
200:
47+
body:
48+
example: !include examples/Foos.json
49+
(testCase):
50+
scenario: No Foos
51+
setupScript: deleteAllFoosIfAny
52+
testScript: getAllFoos
53+
expectedOutput: ""
54+
(testCase):
55+
scenario: One Foo
56+
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
57+
testScript: getAllFoos
58+
expectedOutput: '[ { "id": 999, "name": Joe } ]'
59+
cleanupScript: deleteInputFoos
60+
(testCase):
61+
scenario: Multiple Foos
62+
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
63+
testScript: getAllFoos
64+
expectedOutput: '[ { "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe", "ownerName": "Bob" } ]'
65+
cleanupScript: deleteInputFoos
66+
post:
67+
responses:
68+
200:
69+
body:
70+
example: !include examples/Foo.json
71+
/{fooId}:
72+
type: myResourceTypes.item
73+
get:
74+
responses:
75+
200:
76+
body:
77+
example: !include examples/Foo.json
78+
put:
79+
responses:
80+
200:
81+
body:
82+
example: !include examples/Foo.json
83+
/foos/name/{name}:
84+
get:
85+
description: Get all Foos with the name {name}
86+
responses:
87+
200:
88+
body:
89+
type: myDataTypes.Foo
90+
404:
91+
body:
92+
type: myDataTypes.Error
93+
/foos/bar/{barId}:
94+
get:
95+
description: Get the Foo for the Bar with barId = {barId}
96+
responses:
97+
200:
98+
body:
99+
example: !include examples/Foo.json
100+
/bars:
101+
type: myResourceTypes.collection
102+
get:
103+
queryParameters:
104+
name?: string
105+
ownerName?: string
106+
responses:
107+
200:
108+
body:
109+
example: !include examples/Bars.json
110+
post:
111+
responses:
112+
200:
113+
body:
114+
example: !include examples/Bar.json
115+
/{barId}:
116+
type: myResourceTypes.item
117+
get:
118+
responses:
119+
200:
120+
body:
121+
example: !include examples/Bar.json
122+
put:
123+
responses:
124+
200:
125+
body:
126+
example: !include examples/Bars.json

‎raml/annotations/examples/Bar.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"id" : 1,
3+
"name" : "First Bar",
4+
"city" : "Austin",
5+
"fooId" : 2
6+
}

‎raml/annotations/examples/Bars.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[
2+
{
3+
"id" : 1,
4+
"name" : "First Bar",
5+
"city" : "Austin",
6+
"fooId" : 2
7+
},
8+
{
9+
"id" : 2,
10+
"name" : "Second Bar",
11+
"city" : "Dallas",
12+
"fooId" : 1
13+
},
14+
{
15+
"id" : 3,
16+
"name" : "Third Bar",
17+
"fooId" : 2
18+
}
19+
]

‎raml/annotations/examples/Error.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"message" : "Not found",
3+
"code" : 1001
4+
}

‎raml/annotations/examples/Foo.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"id" : 1,
3+
"name" : "First Foo"
4+
}

‎raml/annotations/examples/Foos.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[
2+
{
3+
"id" : 1,
4+
"name" : "First Foo",
5+
"ownerName" : "Jack Robinson"
6+
},
7+
{
8+
"id" : 2,
9+
"name" : "Second Foo"
10+
},
11+
{
12+
"id" : 3,
13+
"name" : "Third Foo",
14+
"ownerName" : "Chuck Norris"
15+
}
16+
]

‎raml/annotations/extensions/en_US/additionalResources.raml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#%RAML 1.0 Extension
2+
# File located at:
3+
# /extensions/en_US/additionalResources.raml
4+
masterRef: ../../api.raml
5+
usage: This extension defines additional resources for version 2 of the API.
6+
version: v2
7+
/foos:
8+
/bar/{barId}:
9+
get:
10+
description: |
11+
Get the foo that is related to the bar having barId = {barId}
12+
queryParameters:
13+
barId?: integer

‎raml/annotations/libraries/dataTypes.raml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#%RAML 1.0 Library
2+
# This is the file /libraries/dataTypes.raml
3+
usage: This library defines the data types for the API
4+
types:
5+
Foo:
6+
properties:
7+
id: integer
8+
name: string
9+
ownerName?: string
10+
Bar:
11+
properties:
12+
id: integer
13+
name: string
14+
city?: string
15+
fooId: integer
16+
Error:
17+
properties:
18+
code: integer
19+
message: string

‎raml/annotations/libraries/resourceTypes.raml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#%RAML 1.0 Library
2+
# This is the file /libraries/resourceTypes.raml
3+
usage: This library defines the resource types for the API
4+
uses:
5+
myTraits: !include traits.raml
6+
resourceTypes:
7+
collection:
8+
usage: Use this resourceType to represent a collection of items
9+
description: A collection of <<resourcePathName|!uppercamelcase>>
10+
get:
11+
description: |
12+
Get all <<resourcePathName|!uppercamelcase>>,
13+
optionally filtered
14+
is: [ myTraits.hasResponseCollection ]
15+
post:
16+
description: |
17+
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
18+
is: [ myTraits.hasRequestItem ]
19+
item:
20+
usage: Use this resourceType to represent any single item
21+
description: A single <<resourcePathName|!uppercamelcase|!singularize>>
22+
get:
23+
description: |
24+
Get a <<resourcePathName|!uppercamelcase|!singularize>>
25+
by <<resourcePathName|!uppercamelcase|!singularize>>Id
26+
is: [ myTraits.hasResponseItem, myTraits.hasNotFound ]
27+
put:
28+
description: |
29+
Update a <<resourcePathName|!uppercamelcase|!singularize>>
30+
by <<resourcePathName|!singularize>>Id
31+
is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ]
32+
delete:
33+
description: |
34+
Delete a <<resourcePathName|!uppercamelcase|!singularize>>
35+
by <<resourcePathName|!singularize>>Id
36+
is: [ myTraits.hasNotFound ]
37+
responses:
38+
204:

‎raml/annotations/libraries/securitySchemes.raml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#%RAML 1.0 Library
2+
# This is the file /libraries/securitySchemes.raml
3+
securitySchemes:
4+
- basicAuth:
5+
description: Each request must contain the headers necessary for
6+
basic authentication
7+
type: Basic Authentication
8+
describedBy:
9+
headers:
10+
Authorization:
11+
description: |
12+
Used to send the Base64 encoded "username:password"
13+
credentials
14+
type: string
15+
responses:
16+
401:
17+
description: |
18+
Unauthorized. Either the provided username and password
19+
combination is invalid, or the user is not allowed to
20+
access the content provided by the requested URL.

0 commit comments

Comments
 (0)