diff --git a/raml/modularization/api-before-modularization.raml b/raml/modularization/api-before-modularization.raml new file mode 100644 index 0000000000..b580c33983 --- /dev/null +++ b/raml/modularization/api-before-modularization.raml @@ -0,0 +1,119 @@ +#%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. +version: v1 +protocols: [ HTTPS ] +baseUri: http://rest-api.baeldung.com/api/{version} +mediaType: application/json +securedBy: basicAuth +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. +types: + Foo: !include types/Foo.raml + Bar: !include types/Bar.raml + Error: !include types/Error.raml +resourceTypes: + - collection: + usage: Use this resourceType to represent a collection of items + description: A collection of <> + get: + description: | + Get all <>, + optionally filtered + is: [ hasResponseCollection ] + post: + description: | + Create a new <> + is: [ hasRequestItem ] + - item: + usage: Use this resourceType to represent any single item + description: A single <> + get: + description: Get a <> by <> + is: [ hasResponseItem, hasNotFound ] + put: + description: Update a <> by <> + is: [ hasRequestItem, hasResponseItem, hasNotFound ] + delete: + description: Delete a <> by <> + is: [ hasNotFound ] + responses: + 204: +traits: + - hasRequestItem: + body: + application/json: + type: <> + - hasResponseItem: + responses: + 200: + body: + application/json: + type: <> + example: !include examples/<>.json + - hasResponseCollection: + responses: + 200: + body: + application/json: + type: <>[] + example: !include examples/<>.json + - hasNotFound: + responses: + 404: + body: + application/json: + type: Error + example: !include examples/Error.json +/foos: + type: collection + typeName: Foo + get: + queryParameters: + name?: string + ownerName?: string + /{fooId}: + type: item + typeName: Foo + /name/{name}: + get: + description: List all foos with a certain name + typeName: Foo + is: [ hasResponseCollection ] +/bars: + type: collection + typeName: Bar + /{barId}: + type: item + typeName: Bar + /fooId/{fooId}: + get: + description: Get all bars for the matching fooId + typeName: Bar + is: [ hasResponseCollection ] \ No newline at end of file diff --git a/raml/modularization/api-with-libraries.raml b/raml/modularization/api-with-libraries.raml new file mode 100644 index 0000000000..b3081e843a --- /dev/null +++ b/raml/modularization/api-with-libraries.raml @@ -0,0 +1,50 @@ +#%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/security.raml + myDataTypes: !include libraries/dataTypes.raml + myResourceTypes: !include libraries/resourceTypes.raml + myTraits: !include libraries/traits.raml +version: v1 +protocols: [ HTTPS ] +baseUri: http://rest-api.baeldung.com/api/{version} +mediaType: application/json +securedBy: [ mySecuritySchemes.basicAuth ] +/foos: + type: myResourceTypes.collection + typeName: myDataTypes.Foo + get: + queryParameters: + name?: string + ownerName?: string + /{fooId}: + type: myResourceTypes.item + typeName: myDataTypes.Foo + /name/{name}: + get: + description: List all foos with a certain name + typeName: myDataTypes.Foo + is: [ myTraits.hasResponseCollection ] +/bars: + type: myResourceTypes.collection + typeName: myDataTypes.Bar + /{barId}: + type: myResourceTypes.item + typeName: myDataTypes.Bar + /fooId/{fooId}: + get: + description: Get all bars for the matching fooId + type: myResourceTypes.item + typeName: myDataTypes.Bar + is: [ myTraits.hasResponseCollection ] \ No newline at end of file diff --git a/raml/modularization/api-with-typed-fragments.raml b/raml/modularization/api-with-typed-fragments.raml new file mode 100644 index 0000000000..2bb4e317c1 --- /dev/null +++ b/raml/modularization/api-with-typed-fragments.raml @@ -0,0 +1,74 @@ +#%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. +version: v1 +protocols: [ HTTPS ] +baseUri: http://rest-api.baeldung.com/api/{version} +mediaType: application/json +securedBy: [ basicAuth ] +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. +types: + Foo: !include types/Foo.raml + Bar: !include types/Bar.raml + Error: !include types/Error.raml +resourceTypes: + - collection: !include resourceTypes/collection.raml + - item: !include resourceTypes/item.raml +traits: + - hasRequestItem: !include traits/hasRequestItem.raml + - hasResponseItem: !include traits/hasResponseItem.raml + - hasResponseCollection: !include traits/hasResponseCollection.raml + - hasNotFound: !include traits/hasNotFound.raml +/foos: + type: collection + typeName: Foo + get: + queryParameters: + name?: string + ownerName?: string + /{fooId}: + type: item + typeName: Foo + /name/{name}: + get: + description: List all foos with a certain name + typeName: Foo + is: [ hasResponseCollection ] +/bars: + type: collection + typeName: Bar + /{barId}: + type: item + typeName: Bar + /fooId/{fooId}: + get: + description: Get all bars for the matching fooId + typeName: Bar + is: [ hasResponseCollection ] \ No newline at end of file diff --git a/raml/modularization/api.raml b/raml/modularization/api.raml new file mode 100644 index 0000000000..184027cd26 --- /dev/null +++ b/raml/modularization/api.raml @@ -0,0 +1,47 @@ +#%RAML 1.0 +title: Baeldung Foo REST Services API +uses: + security: !include libraries/security.raml +version: v1 +protocols: [ HTTPS ] +baseUri: http://rest-api.baeldung.com/api/{version} +mediaType: application/json +securedBy: [ security.basicAuth ] +types: + Foo: !include types/Foo.raml + Bar: !include types/Bar.raml + Error: !include types/Error.raml +resourceTypes: + - collection: !include resourceTypes/collection.raml + - item: !include resourceTypes/item.raml +traits: + - hasRequestItem: !include traits/hasRequestItem.raml + - hasResponseItem: !include traits/hasResponseItem.raml + - hasResponseCollection: !include traits/hasResponseCollection.raml + - hasNotFound: !include traits/hasNotFound.raml +/foos: + type: collection + typeName: Foo + get: + queryParameters: + name?: string + ownerName?: string + /{fooId}: + type: item + typeName: Foo + /name/{name}: + get: + description: List all foos with a certain name + typeName: Foo + is: [ hasResponseCollection ] +/bars: + type: collection + typeName: Bar + /{barId}: + type: item + typeName: Bar + /fooId/{fooId}: + get: + description: Get all bars for the matching fooId + typeName: Bar + is: [ hasResponseCollection ] \ No newline at end of file diff --git a/raml/modularization/examples/Bar.json b/raml/modularization/examples/Bar.json new file mode 100644 index 0000000000..0ee1b34edb --- /dev/null +++ b/raml/modularization/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/modularization/examples/Bars.json b/raml/modularization/examples/Bars.json new file mode 100644 index 0000000000..89ea875432 --- /dev/null +++ b/raml/modularization/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/modularization/examples/Error.json b/raml/modularization/examples/Error.json new file mode 100644 index 0000000000..dca56da7c2 --- /dev/null +++ b/raml/modularization/examples/Error.json @@ -0,0 +1,4 @@ +{ + "message" : "Not found", + "code" : 1001 +} \ No newline at end of file diff --git a/raml/modularization/examples/Foo.json b/raml/modularization/examples/Foo.json new file mode 100644 index 0000000000..1b1b8c891e --- /dev/null +++ b/raml/modularization/examples/Foo.json @@ -0,0 +1,4 @@ +{ + "id" : 1, + "name" : "First Foo" +} \ No newline at end of file diff --git a/raml/modularization/examples/Foos.json b/raml/modularization/examples/Foos.json new file mode 100644 index 0000000000..74f64689f0 --- /dev/null +++ b/raml/modularization/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/modularization/extensions/en_US/additionalResources.raml b/raml/modularization/extensions/en_US/additionalResources.raml new file mode 100644 index 0000000000..20c6851f23 --- /dev/null +++ b/raml/modularization/extensions/en_US/additionalResources.raml @@ -0,0 +1,16 @@ +#%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} + typeName: Foo + queryParameters: + barId?: integer + typeName: Foo + is: [ hasResponseItem ] diff --git a/raml/modularization/libraries/dataTypes.raml b/raml/modularization/libraries/dataTypes.raml new file mode 100644 index 0000000000..8a240e62dc --- /dev/null +++ b/raml/modularization/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/modularization/libraries/resourceTypes.raml b/raml/modularization/libraries/resourceTypes.raml new file mode 100644 index 0000000000..681ff710d6 --- /dev/null +++ b/raml/modularization/libraries/resourceTypes.raml @@ -0,0 +1,32 @@ +#%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 <> + is: [ myTraits.hasResponseItem, myTraits.hasNotFound ] + put: + description: Update a <> by <> + is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ] + delete: + description: Delete a <> by <> + is: [ myTraits.hasNotFound ] + responses: + 204: diff --git a/raml/modularization/libraries/securitySchemes.raml b/raml/modularization/libraries/securitySchemes.raml new file mode 100644 index 0000000000..621c6ac975 --- /dev/null +++ b/raml/modularization/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/modularization/libraries/traits.raml b/raml/modularization/libraries/traits.raml new file mode 100644 index 0000000000..c101d94c02 --- /dev/null +++ b/raml/modularization/libraries/traits.raml @@ -0,0 +1,33 @@ +#%RAML 1.0 Library +# This is the file /libraries/traits.raml +usage: This library defines some basic traits +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: <> + example: !include /examples/<>.json + hasResponseCollection: + usage: Use this trait for resources whose response body is a collection of items + responses: + 200: + body: + application/json: + type: <>[] + example: !include /examples/<>.json + hasNotFound: + usage: Use this trait for resources that could respond with a 404 status + responses: + 404: + body: + application/json: + type: Error + example: !include /examples/Error.json diff --git a/raml/modularization/overlays/es_ES/additionalResources.raml b/raml/modularization/overlays/es_ES/additionalResources.raml new file mode 100644 index 0000000000..e8748fd726 --- /dev/null +++ b/raml/modularization/overlays/es_ES/additionalResources.raml @@ -0,0 +1,13 @@ +#%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 2 del API. +version: v2 +/foos: + /bar/{barId}: + get: + description: | + Obtener el foo que se relaciona con el bar tomando barId = {barId} diff --git a/raml/modularization/overlays/es_ES/documentationItems.raml b/raml/modularization/overlays/es_ES/documentationItems.raml new file mode 100644 index 0000000000..dc6ca3eaef --- /dev/null +++ b/raml/modularization/overlays/es_ES/documentationItems.raml @@ -0,0 +1,23 @@ +#%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. diff --git a/raml/modularization/resourceTypes/collection.raml b/raml/modularization/resourceTypes/collection.raml new file mode 100644 index 0000000000..0cab417f14 --- /dev/null +++ b/raml/modularization/resourceTypes/collection.raml @@ -0,0 +1,12 @@ +#%RAML 1.0 ResourceType +usage: Use this resourceType to represent a collection of items +description: A collection of <> +get: + description: | + Get all <>, + optionally filtered + is: [ hasResponseCollection ] +post: + description: | + Create a new <> + is: [ hasRequestItem ] diff --git a/raml/modularization/resourceTypes/item.raml b/raml/modularization/resourceTypes/item.raml new file mode 100644 index 0000000000..59f057ca98 --- /dev/null +++ b/raml/modularization/resourceTypes/item.raml @@ -0,0 +1,14 @@ +#%RAML 1.0 ResourceType +usage: Use this resourceType to represent any single item +description: A single <> +get: + description: Get a <> by <> + is: [ hasResponseItem, hasNotFound ] +put: + description: Update a <> by <> + is: [ hasRequestItem, hasResponseItem, hasNotFound ] +delete: + description: Delete a <> by <> + is: [ hasNotFound ] + responses: + 204: diff --git a/raml/modularization/traits/hasNotFound.raml b/raml/modularization/traits/hasNotFound.raml new file mode 100644 index 0000000000..8d2d940c03 --- /dev/null +++ b/raml/modularization/traits/hasNotFound.raml @@ -0,0 +1,8 @@ +#%RAML 1.0 Trait +usage: Use this trait for resources that could respond with a 404 status +responses: + 404: + body: + application/json: + type: Error + example: !include /examples/Error.json diff --git a/raml/modularization/traits/hasRequestItem.raml b/raml/modularization/traits/hasRequestItem.raml new file mode 100644 index 0000000000..06281781c0 --- /dev/null +++ b/raml/modularization/traits/hasRequestItem.raml @@ -0,0 +1,5 @@ +#%RAML 1.0 Trait +usage: Use this trait for resources whose request body is a single item +body: + application/json: + type: <> diff --git a/raml/modularization/traits/hasResponseCollection.raml b/raml/modularization/traits/hasResponseCollection.raml new file mode 100644 index 0000000000..47dc1c2d5f --- /dev/null +++ b/raml/modularization/traits/hasResponseCollection.raml @@ -0,0 +1,8 @@ +#%RAML 1.0 Trait +usage: Use this trait for resources whose response body is a collection of items +responses: + 200: + body: + application/json: + type: <>[] + example: !include /examples/<>.json diff --git a/raml/modularization/traits/hasResponseItem.raml b/raml/modularization/traits/hasResponseItem.raml new file mode 100644 index 0000000000..94d3ba0756 --- /dev/null +++ b/raml/modularization/traits/hasResponseItem.raml @@ -0,0 +1,8 @@ +#%RAML 1.0 Trait +usage: Use this trait for resources whose response body is a single item +responses: + 200: + body: + application/json: + type: <> + example: !include /examples/<>.json diff --git a/raml/modularization/types/Bar.raml b/raml/modularization/types/Bar.raml new file mode 100644 index 0000000000..92255a75fe --- /dev/null +++ b/raml/modularization/types/Bar.raml @@ -0,0 +1,7 @@ +#%RAML 1.0 DataType + +properties: + id: integer + name: string + city?: string + fooId: integer diff --git a/raml/modularization/types/Error.raml b/raml/modularization/types/Error.raml new file mode 100644 index 0000000000..8d54b5f181 --- /dev/null +++ b/raml/modularization/types/Error.raml @@ -0,0 +1,5 @@ +#%RAML 1.0 DataType + + properties: + code: integer + message: string diff --git a/raml/modularization/types/Foo.raml b/raml/modularization/types/Foo.raml new file mode 100644 index 0000000000..1702865e05 --- /dev/null +++ b/raml/modularization/types/Foo.raml @@ -0,0 +1,6 @@ +#%RAML 1.0 DataType + +properties: + id: integer + name: string + ownerName?: string