From 7fb50bfaed8280acf7c4dbdf486087dac7d2b7b0 Mon Sep 17 00:00:00 2001 From: Kevin Gilmore Date: Wed, 17 Feb 2016 11:38:29 -0600 Subject: [PATCH] Added files for RAML annotations article --- raml/annotations/api.raml | 126 ++++++++++++++++++ raml/annotations/examples/Bar.json | 6 + raml/annotations/examples/Bars.json | 19 +++ raml/annotations/examples/Error.json | 4 + raml/annotations/examples/Foo.json | 4 + raml/annotations/examples/Foos.json | 16 +++ .../extensions/en_US/additionalResources.raml | 13 ++ raml/annotations/libraries/dataTypes.raml | 19 +++ raml/annotations/libraries/resourceTypes.raml | 38 ++++++ .../libraries/securitySchemes.raml | 20 +++ raml/annotations/libraries/traits.raml | 32 +++++ .../overlays/es_ES/additionalResources.raml | 11 ++ .../overlays/es_ES/documentationItems.raml | 22 +++ 13 files changed, 330 insertions(+) create mode 100644 raml/annotations/api.raml create mode 100644 raml/annotations/examples/Bar.json create mode 100644 raml/annotations/examples/Bars.json create mode 100644 raml/annotations/examples/Error.json create mode 100644 raml/annotations/examples/Foo.json create mode 100644 raml/annotations/examples/Foos.json create mode 100644 raml/annotations/extensions/en_US/additionalResources.raml create mode 100644 raml/annotations/libraries/dataTypes.raml create mode 100644 raml/annotations/libraries/resourceTypes.raml create mode 100644 raml/annotations/libraries/securitySchemes.raml create mode 100644 raml/annotations/libraries/traits.raml create mode 100644 raml/annotations/overlays/es_ES/additionalResources.raml create mode 100644 raml/annotations/overlays/es_ES/documentationItems.raml diff --git a/raml/annotations/api.raml b/raml/annotations/api.raml new file mode 100644 index 0000000000..e0123536eb --- /dev/null +++ b/raml/annotations/api.raml @@ -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 diff --git a/raml/annotations/examples/Bar.json b/raml/annotations/examples/Bar.json new file mode 100644 index 0000000000..0ee1b34edb --- /dev/null +++ b/raml/annotations/examples/Bar.json @@ -0,0 +1,6 @@ +{ + "id" : 1, + "name" : "First Bar", + "city" : "Austin", + "fooId" : 2 +} \ No newline at end of file diff --git a/raml/annotations/examples/Bars.json b/raml/annotations/examples/Bars.json new file mode 100644 index 0000000000..89ea875432 --- /dev/null +++ b/raml/annotations/examples/Bars.json @@ -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 + } +] \ No newline at end of file diff --git a/raml/annotations/examples/Error.json b/raml/annotations/examples/Error.json new file mode 100644 index 0000000000..dca56da7c2 --- /dev/null +++ b/raml/annotations/examples/Error.json @@ -0,0 +1,4 @@ +{ + "message" : "Not found", + "code" : 1001 +} \ No newline at end of file diff --git a/raml/annotations/examples/Foo.json b/raml/annotations/examples/Foo.json new file mode 100644 index 0000000000..1b1b8c891e --- /dev/null +++ b/raml/annotations/examples/Foo.json @@ -0,0 +1,4 @@ +{ + "id" : 1, + "name" : "First Foo" +} \ No newline at end of file diff --git a/raml/annotations/examples/Foos.json b/raml/annotations/examples/Foos.json new file mode 100644 index 0000000000..74f64689f0 --- /dev/null +++ b/raml/annotations/examples/Foos.json @@ -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" + } +] \ No newline at end of file diff --git a/raml/annotations/extensions/en_US/additionalResources.raml b/raml/annotations/extensions/en_US/additionalResources.raml new file mode 100644 index 0000000000..9ab0d0a243 --- /dev/null +++ b/raml/annotations/extensions/en_US/additionalResources.raml @@ -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 diff --git a/raml/annotations/libraries/dataTypes.raml b/raml/annotations/libraries/dataTypes.raml new file mode 100644 index 0000000000..8a240e62dc --- /dev/null +++ b/raml/annotations/libraries/dataTypes.raml @@ -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 diff --git a/raml/annotations/libraries/resourceTypes.raml b/raml/annotations/libraries/resourceTypes.raml new file mode 100644 index 0000000000..fb054f1a36 --- /dev/null +++ b/raml/annotations/libraries/resourceTypes.raml @@ -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 <> + get: + description: | + Get all <>, + optionally filtered + is: [ myTraits.hasResponseCollection ] + post: + description: | + Create a new <> + is: [ myTraits.hasRequestItem ] + item: + usage: Use this resourceType to represent any single item + description: A single <> + get: + description: | + Get a <> + by <>Id + is: [ myTraits.hasResponseItem, myTraits.hasNotFound ] + put: + description: | + Update a <> + by <>Id + is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ] + delete: + description: | + Delete a <> + by <>Id + is: [ myTraits.hasNotFound ] + responses: + 204: diff --git a/raml/annotations/libraries/securitySchemes.raml b/raml/annotations/libraries/securitySchemes.raml new file mode 100644 index 0000000000..621c6ac975 --- /dev/null +++ b/raml/annotations/libraries/securitySchemes.raml @@ -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. diff --git a/raml/annotations/libraries/traits.raml b/raml/annotations/libraries/traits.raml new file mode 100644 index 0000000000..610747e79f --- /dev/null +++ b/raml/annotations/libraries/traits.raml @@ -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: <> + hasResponseItem: + usage: Use this trait for resources whose response body is a single item + responses: + 200: + body: + application/json: + type: <> + hasResponseCollection: + usage: Use this trait for resources whose response body is a collection of items + responses: + 200: + body: + application/json: + type: <>[] + hasNotFound: + usage: Use this trait for resources that could respond with a 404 status + responses: + 404: + body: + application/json: + type: myDataTypes.Error diff --git a/raml/annotations/overlays/es_ES/additionalResources.raml b/raml/annotations/overlays/es_ES/additionalResources.raml new file mode 100644 index 0000000000..0edd6a9231 --- /dev/null +++ b/raml/annotations/overlays/es_ES/additionalResources.raml @@ -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} diff --git a/raml/annotations/overlays/es_ES/documentationItems.raml b/raml/annotations/overlays/es_ES/documentationItems.raml new file mode 100644 index 0000000000..49dd46fb59 --- /dev/null +++ b/raml/annotations/overlays/es_ES/documentationItems.raml @@ -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.