Merge pull request #358 from KevinGilmore/master
RAML Annotations article
This commit is contained in:
Eugen
commit
ff56088c4a
|
|
@ -0,0 +1,126 @@
|
|||
#%RAML 1.0
|
||||
title: API for REST Services used in the RAML tutorials on Baeldung.com
|
||||
documentation:
|
||||
- title: Overview
|
||||
content: |
|
||||
This document defines the interface for the REST services
|
||||
used in the popular RAML Tutorial series at Baeldung.com.
|
||||
- title: Disclaimer
|
||||
content: |
|
||||
All names used in this definition are purely fictional.
|
||||
Any similarities between the names used in this tutorial and those of real persons, whether living or dead, are merely coincidental.
|
||||
- title: Copyright
|
||||
content: Copyright 2016 by Baeldung.com. All rights reserved.
|
||||
uses:
|
||||
mySecuritySchemes: !include libraries/securitySchemes.raml
|
||||
myDataTypes: !include libraries/dataTypes.raml
|
||||
myTraits: !include libraries/traits.raml
|
||||
myResourceTypes: !include libraries/resourceTypes.raml
|
||||
version: v1
|
||||
protocols: [ HTTPS ]
|
||||
baseUri: http://rest-api.baeldung.com/api/{version}
|
||||
mediaType: application/json
|
||||
securedBy: [ mySecuritySchemes.basicAuth ]
|
||||
annotationTypes:
|
||||
testCase:
|
||||
allowedTargets: [ Method ]
|
||||
allowMultiple: true
|
||||
usage: |
|
||||
Use this annotation to declare a test case
|
||||
within a testSuite declaration.
|
||||
You may apply this annotation multiple times
|
||||
within the target testSuite.
|
||||
properties:
|
||||
scenario: string
|
||||
setupScript?: string[]
|
||||
testScript: string[]
|
||||
expectedOutput?: string
|
||||
cleanupScript?: string[]
|
||||
/foos:
|
||||
type: myResourceTypes.collection
|
||||
get:
|
||||
queryParameters:
|
||||
name?: string
|
||||
ownerName?: string
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Foos.json
|
||||
(testCase):
|
||||
scenario: No Foos
|
||||
setupScript: deleteAllFoosIfAny
|
||||
testScript: getAllFoos
|
||||
expectedOutput: ""
|
||||
(testCase):
|
||||
scenario: One Foo
|
||||
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
|
||||
testScript: getAllFoos
|
||||
expectedOutput: '[ { "id": 999, "name": Joe } ]'
|
||||
cleanupScript: deleteInputFoos
|
||||
(testCase):
|
||||
scenario: Multiple Foos
|
||||
setupScript: [ deleteAllFoosIfAny, addInputFoos ]
|
||||
testScript: getAllFoos
|
||||
expectedOutput: '[ { "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe", "ownerName": "Bob" } ]'
|
||||
cleanupScript: deleteInputFoos
|
||||
post:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Foo.json
|
||||
/{fooId}:
|
||||
type: myResourceTypes.item
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Foo.json
|
||||
put:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Foo.json
|
||||
/foos/name/{name}:
|
||||
get:
|
||||
description: Get all Foos with the name {name}
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
type: myDataTypes.Foo
|
||||
404:
|
||||
body:
|
||||
type: myDataTypes.Error
|
||||
/foos/bar/{barId}:
|
||||
get:
|
||||
description: Get the Foo for the Bar with barId = {barId}
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Foo.json
|
||||
/bars:
|
||||
type: myResourceTypes.collection
|
||||
get:
|
||||
queryParameters:
|
||||
name?: string
|
||||
ownerName?: string
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Bars.json
|
||||
post:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Bar.json
|
||||
/{barId}:
|
||||
type: myResourceTypes.item
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Bar.json
|
||||
put:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
example: !include examples/Bars.json
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
{
|
||||
"id" : 1,
|
||||
"name" : "First Bar",
|
||||
"city" : "Austin",
|
||||
"fooId" : 2
|
||||
}
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
[
|
||||
{
|
||||
"id" : 1,
|
||||
"name" : "First Bar",
|
||||
"city" : "Austin",
|
||||
"fooId" : 2
|
||||
},
|
||||
{
|
||||
"id" : 2,
|
||||
"name" : "Second Bar",
|
||||
"city" : "Dallas",
|
||||
"fooId" : 1
|
||||
},
|
||||
{
|
||||
"id" : 3,
|
||||
"name" : "Third Bar",
|
||||
"fooId" : 2
|
||||
}
|
||||
]
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"message" : "Not found",
|
||||
"code" : 1001
|
||||
}
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"id" : 1,
|
||||
"name" : "First Foo"
|
||||
}
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[
|
||||
{
|
||||
"id" : 1,
|
||||
"name" : "First Foo",
|
||||
"ownerName" : "Jack Robinson"
|
||||
},
|
||||
{
|
||||
"id" : 2,
|
||||
"name" : "Second Foo"
|
||||
},
|
||||
{
|
||||
"id" : 3,
|
||||
"name" : "Third Foo",
|
||||
"ownerName" : "Chuck Norris"
|
||||
}
|
||||
]
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
#%RAML 1.0 Extension
|
||||
# File located at:
|
||||
# /extensions/en_US/additionalResources.raml
|
||||
masterRef: ../../api.raml
|
||||
usage: This extension defines additional resources for version 2 of the API.
|
||||
version: v2
|
||||
/foos:
|
||||
/bar/{barId}:
|
||||
get:
|
||||
description: |
|
||||
Get the foo that is related to the bar having barId = {barId}
|
||||
queryParameters:
|
||||
barId?: integer
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
#%RAML 1.0 Library
|
||||
# This is the file /libraries/dataTypes.raml
|
||||
usage: This library defines the data types for the API
|
||||
types:
|
||||
Foo:
|
||||
properties:
|
||||
id: integer
|
||||
name: string
|
||||
ownerName?: string
|
||||
Bar:
|
||||
properties:
|
||||
id: integer
|
||||
name: string
|
||||
city?: string
|
||||
fooId: integer
|
||||
Error:
|
||||
properties:
|
||||
code: integer
|
||||
message: string
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
#%RAML 1.0 Library
|
||||
# This is the file /libraries/resourceTypes.raml
|
||||
usage: This library defines the resource types for the API
|
||||
uses:
|
||||
myTraits: !include traits.raml
|
||||
resourceTypes:
|
||||
collection:
|
||||
usage: Use this resourceType to represent a collection of items
|
||||
description: A collection of <<resourcePathName|!uppercamelcase>>
|
||||
get:
|
||||
description: |
|
||||
Get all <<resourcePathName|!uppercamelcase>>,
|
||||
optionally filtered
|
||||
is: [ myTraits.hasResponseCollection ]
|
||||
post:
|
||||
description: |
|
||||
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
is: [ myTraits.hasRequestItem ]
|
||||
item:
|
||||
usage: Use this resourceType to represent any single item
|
||||
description: A single <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
get:
|
||||
description: |
|
||||
Get a <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
by <<resourcePathName|!uppercamelcase|!singularize>>Id
|
||||
is: [ myTraits.hasResponseItem, myTraits.hasNotFound ]
|
||||
put:
|
||||
description: |
|
||||
Update a <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
by <<resourcePathName|!singularize>>Id
|
||||
is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ]
|
||||
delete:
|
||||
description: |
|
||||
Delete a <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
by <<resourcePathName|!singularize>>Id
|
||||
is: [ myTraits.hasNotFound ]
|
||||
responses:
|
||||
204:
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
#%RAML 1.0 Library
|
||||
# This is the file /libraries/securitySchemes.raml
|
||||
securitySchemes:
|
||||
- basicAuth:
|
||||
description: Each request must contain the headers necessary for
|
||||
basic authentication
|
||||
type: Basic Authentication
|
||||
describedBy:
|
||||
headers:
|
||||
Authorization:
|
||||
description: |
|
||||
Used to send the Base64 encoded "username:password"
|
||||
credentials
|
||||
type: string
|
||||
responses:
|
||||
401:
|
||||
description: |
|
||||
Unauthorized. Either the provided username and password
|
||||
combination is invalid, or the user is not allowed to
|
||||
access the content provided by the requested URL.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
#%RAML 1.0 Library
|
||||
# This is the file /libraries/traits.raml
|
||||
usage: This library defines some basic traits
|
||||
uses:
|
||||
myDataTypes: !include dataTypes.raml
|
||||
traits:
|
||||
hasRequestItem:
|
||||
usage: Use this trait for resources whose request body is a single item
|
||||
body:
|
||||
application/json:
|
||||
type: <<resourcePathName|!singularize>>
|
||||
hasResponseItem:
|
||||
usage: Use this trait for resources whose response body is a single item
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<resourcePathName|!singularize>>
|
||||
hasResponseCollection:
|
||||
usage: Use this trait for resources whose response body is a collection of items
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<resourcePathName|!singularize>>[]
|
||||
hasNotFound:
|
||||
usage: Use this trait for resources that could respond with a 404 status
|
||||
responses:
|
||||
404:
|
||||
body:
|
||||
application/json:
|
||||
type: myDataTypes.Error
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
#%RAML 1.0 Overlay
|
||||
# Archivo situado en:
|
||||
# /overlays/es_ES/additionalResources.raml
|
||||
masterRef: ../../api.raml
|
||||
usage: |
|
||||
Se trata de un español demasiado que describe los recursos adicionales
|
||||
para la versión 1 del API.
|
||||
/foos/bar/{barId}:
|
||||
get:
|
||||
description: |
|
||||
Obtener el foo que se relaciona con el bar tomando barId = {barId}
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
#%RAML 1.0 Overlay
|
||||
# File located at (archivo situado en):
|
||||
# /overlays/es_ES/documentationItems.raml
|
||||
masterRef: ../../api.raml
|
||||
usage: |
|
||||
To provide user documentation and other descriptive text in Spanish
|
||||
(Para proporcionar la documentación del usuario y otro texto descriptivo en español)
|
||||
title: API para servicios REST utilizados en los tutoriales RAML en Baeldung.com
|
||||
documentation:
|
||||
- title: Descripción general
|
||||
content: |
|
||||
Este documento define la interfaz para los servicios REST
|
||||
utilizados en la popular serie de RAML Tutorial en Baeldung.com
|
||||
- title: Renuncia
|
||||
content: |
|
||||
Todos los nombres usados en esta definición son pura ficción.
|
||||
Cualquier similitud entre los nombres utilizados en este tutorial
|
||||
y los de las personas reales, ya sea vivo o muerto,
|
||||
no son más que coincidenta.
|
||||
- title: Derechos de autor
|
||||
content: |
|
||||
Derechos de autor 2016 por Baeldung.com. Todos los derechos reservados.
|
||||
Loading…
Reference in New Issue