Merge pull request #353 from KevinGilmore/master
PR for RAML Modularization article
This commit is contained in:
Eugen
commit
8cc8b37f92
|
|
@ -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 <<resourcePathName|!uppercamelcase>>
|
||||
get:
|
||||
description: |
|
||||
Get all <<resourcePathName|!uppercamelcase>>,
|
||||
optionally filtered
|
||||
is: [ hasResponseCollection ]
|
||||
post:
|
||||
description: |
|
||||
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
is: [ hasRequestItem ]
|
||||
- item:
|
||||
usage: Use this resourceType to represent any single item
|
||||
description: A single <<typeName>>
|
||||
get:
|
||||
description: Get a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasResponseItem, hasNotFound ]
|
||||
put:
|
||||
description: Update a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasRequestItem, hasResponseItem, hasNotFound ]
|
||||
delete:
|
||||
description: Delete a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasNotFound ]
|
||||
responses:
|
||||
204:
|
||||
traits:
|
||||
- hasRequestItem:
|
||||
body:
|
||||
application/json:
|
||||
type: <<typeName>>
|
||||
- hasResponseItem:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<typeName>>
|
||||
example: !include examples/<<typeName>>.json
|
||||
- hasResponseCollection:
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<typeName>>[]
|
||||
example: !include examples/<<typeName|!pluralize>>.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 ]
|
||||
|
|
@ -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 ]
|
||||
|
|
@ -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 ]
|
||||
|
|
@ -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 ]
|
||||
|
|
@ -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,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 ]
|
||||
|
|
@ -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,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 <<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 <<typeName>>
|
||||
get:
|
||||
description: Get a <<typeName>> by <<resourcePathName>>
|
||||
is: [ myTraits.hasResponseItem, myTraits.hasNotFound ]
|
||||
put:
|
||||
description: Update a <<typeName>> by <<resourcePathName>>
|
||||
is: [ myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound ]
|
||||
delete:
|
||||
description: Delete a <<typeName>> by <<resourcePathName>>
|
||||
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,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: <<typeName>>
|
||||
hasResponseItem:
|
||||
usage: Use this trait for resources whose response body is a single item
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<typeName>>
|
||||
example: !include /examples/<<typeName>>.json
|
||||
hasResponseCollection:
|
||||
usage: Use this trait for resources whose response body is a collection of items
|
||||
responses:
|
||||
200:
|
||||
body:
|
||||
application/json:
|
||||
type: <<typeName>>[]
|
||||
example: !include /examples/<<typeName|!pluralize>>.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
|
||||
|
|
@ -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}
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
#%RAML 1.0 ResourceType
|
||||
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: [ hasResponseCollection ]
|
||||
post:
|
||||
description: |
|
||||
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
|
||||
is: [ hasRequestItem ]
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
#%RAML 1.0 ResourceType
|
||||
usage: Use this resourceType to represent any single item
|
||||
description: A single <<typeName>>
|
||||
get:
|
||||
description: Get a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasResponseItem, hasNotFound ]
|
||||
put:
|
||||
description: Update a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasRequestItem, hasResponseItem, hasNotFound ]
|
||||
delete:
|
||||
description: Delete a <<typeName>> by <<resourcePathName>>
|
||||
is: [ hasNotFound ]
|
||||
responses:
|
||||
204:
|
||||
|
|
@ -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
|
||||
|
|
@ -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: <<typeName>>
|
||||
|
|
@ -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: <<typeName>>[]
|
||||
example: !include /examples/<<typeName|!pluralize>>.json
|
||||
|
|
@ -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: <<typeName>>
|
||||
example: !include /examples/<<typeName>>.json
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
#%RAML 1.0 DataType
|
||||
|
||||
properties:
|
||||
id: integer
|
||||
name: string
|
||||
city?: string
|
||||
fooId: integer
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
#%RAML 1.0 DataType
|
||||
|
||||
properties:
|
||||
code: integer
|
||||
message: string
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
#%RAML 1.0 DataType
|
||||
|
||||
properties:
|
||||
id: integer
|
||||
name: string
|
||||
ownerName?: string
|
||||
Loading…
Reference in New Issue