Swagger and RAML Document Support for Describing External REST APIs
The REST Adapter provides support for consuming REST APIs that are described in either a Swagger or RAML document.
-
RESTful API Modeling Language (RAML): A language for describing RESTful APIs. RAML provides the information necessary to describe RESTful or practically-RESTful APIs (APIs that do not obey all REST constraints). See REST Adapter Trigger Resource Configuration Page.
-
Swagger: A specification for describing, producing, consuming, and visualizing RESTful web services. See Configure the REST Adapter to Consume an External REST API Described Using a Swagger Document.
-
/Book. This resource containsgetandpostmethods and/Book/{id},/Book/hello, and/Book/searchsubresources. -
/Author. This resource contains agetmethod and an/Author/{id}subresource.
When configuring an invoke (outbound) REST Adapter in the Adapter Endpoint Configuration Wizard, the resources and subresources are displayed for selection as business objects and the methods are displayed for selection as operations to perform on the business objects.
When creating the REST Adapter connection, you select Swagger Definition URL in the Connection Type field and specify the URL in the Connection URL field of the Connection Properties dialog. See Configure Connection Properties for Invoke Connections.
{
"swagger" : "2.0",
"info" : {
"version" : "1.0",
"title" : "RestServiceForBooks"
},
"host" : "host_name:8080",
"basePath" : "/Test/rest",
"schemes" : ["http"],
"paths" : {
"/Book" : {
"get" : {
"operationId" : "getBooks",
"description" : "Returns all the available books in the store",
"produces" : [ "application/xml", "application/json" ],
"responses" : {
"default" : {
"schema" : {
"$ref" : "#/definitions/Books"
}
}
}
},
"post" : {
"operationId" : "postBook",
"description" : "Creates a new book item",
"produces" : [ "application/xml", "application/json" ],
"consumes" : [ "application/xml", "application/json" ],
"parameters" : [
{
"name" : "Book",
"in" : "body",
"required" : true,
"schema" : { "$ref" : "#/definitions/Book" }
}
],
"responses" : {
"default" : {
"schema" : { "$ref" : "#/definitions/Book" }
}
}
}
},
"/Book/{id}" : {
"get" : {
"operationId" : "getSingleBook",
"description" : "Returns a book with specific id",
"produces" : [ "application/xml", "application/json" ],
"parameters" : [
{
"name": "id",
"in": "path",
"required" : true,
"type" : "string"
}
],
"responses" : {
"default" : {
"schema" : { "$ref" : "#/definitions/Book" }
}
}
}
},
"/Book/hello" : {
"get" : {
"operationId" : "sayHelloToBook",
"description" : "says hello to a book",
"produces" : [ "application/xml", "application/json" ],
"responses" : {
"default" : {
"schema" : { "type" : "string" }
}
}
}
},
"/Book/search" : {
"get" : {
"operationId" : "searchBook",
"description" : "Returns a list of books that match query param",
"produces" : [ "application/xml", "application/json" ],
"parameters" : [
{
"name": "name",
"in": "query",
"required" : false,
"type" : "string"
}
],
"responses" : {
"default" : {
"schema" : {
"$ref" : "#/definitions/Books"
}
}
}
}
},
"/Author" : {
"get" : {
"operationId" : "getAuthors",
"description": "Returns a list of authors",
"produces": [
"application/xml",
"application/json"
],
"responses": {
"default": {
"schema": {
"$ref" : "#/definitions/Authors"
}
}
}
}
},
"/Author/{id}" : {
"get" : {
"operationId" : "getSingleAuthor",
"description" : "Returns a Author with specific id",
"produces" : [ "application/xml", "application/json" ],
"parameters" : [
{
"name": "id",
"in": "path",
"required" : true,
"type" : "string"
}
],
"responses" : {
"default" : {
"schema" : { "$ref" : "#/definitions/Author" }
}
}
}
}
},
"definitions" : {
"Author" : {
"type" : "object",
"properties" : {
"id" : { "type" : "string" },
"firstName" : { "type" : "string"},
"lastName" : { "type" : "string" }
},
"required" : [ "id", "firstName", "lastName"]
},
"Authors" : {
"type" : "object",
"properties" : {
"items" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Author"
}
}
}
},
"Publisher" : {
"type" : "object",
"properties" : {
"id" : { "type" : "string" },
"name" : { "type" : "string"},
"location" : { "type" : "string" }
},
"required" : [ "id", "name", "location"]
},
"Publishers" : {
"type" : "object",
"properties" : {
"items" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Publisher"
}
}
}
},
"Book" : {
"type" : "object",
"properties" : {
"id" : { "type" : "string" },
"name" : { "type" : "string" },
"ISBN" : { "type" : "string" },
"price" : { "type" : "integer" },
"author" : { "type" : "array", "items" :{ "$ref" : "#/definitions/Author" } },
"publisher" : { "$ref" : "#/definitions/Publisher" }
},
"required" : ["id", "name", "ISBN", "price", "author", "publisher" ]
},
"Books" : {
"type" : "object",
"properties" : {
"items" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Book"
}
}
}
}
}
}
The following example shows a RAML file. The file contains the schemas that use the service. This file contains two main resources:
-
/Author. This resource contains agetmethod and an/Author/{id}subresource. -
/Book. This resource containsgetandpostmethods and/Book/{id}and/Book/searchsubresources.
When configuring an invoke (outbound) REST Adapter in the Adapter Endpoint Configuration Wizard, the resources and subresources are displayed for selection as business objects and the methods are displayed for selection as operations to perform on the business objects.
When creating your REST Adapter connection, you select RAML Definition URL in the Connection Type field and specify the URL in the Connection URL field of the Connection Properties dialog.
#%RAML 0.8
title: API for Books
version: v1
baseUri: "http://host_name:8080/Test/rest"
protocols: [ HTTP ]
schemas:
- authors-jsonschema: |
{
"$schema" : "http://json-schema.org/draft-03/schema",
"type":"object",
"properties":{
"items":{
"type":"array",
"items":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"firstName":{
"type":"string"
},
"lastName":{
"type":"string"
}
},
"required":[
"id",
"firstName",
"lastName"
]
}
}
}
}
- author-jsonschema: |
{
"$schema":"http://json-schema.org/draft-03/schema",
"type":"object",
"properties":{
"id":{
"type":"string"
},
"firstName":{
"type":"string"
},
"lastName":{
"type":"string"
}
},
"required":[
"id",
"firstName",
"lastName"
]
}
- books-jsonschema: |
{
"$schema":"http://json-schema.org/draft-03/schema",
"type":"object",
"properties":{
"items":{
"type":"array",
"items":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"name":{
"type":"string"
},
"ISBN":{
"type":"string"
},
"price":{
"type":"integer"
},
"author":{
"type":"array",
"items":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"firstName":{
"type":"string"
},
"lastName":{
"type":"string"
}
},
"required":[
"id",
"firstName",
"lastName"
]
}
},
"publisher":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"name":{
"type":"string"
},
"location":{
"type":"string"
}
},
"required":[
"id",
"name",
"location"
]
}
},
"required":[
"id",
"name",
"ISBN",
"price",
"author",
"publisher"
]
}
}
}
}
- book-jsonschema: |
{
"$schema":"http://json-schema.org/draft-03/schema",
"type":"object",
"properties":{
"id":{
"type":"string"
},
"name":{
"type":"string"
},
"ISBN":{
"type":"string"
},
"price":{
"type":"integer"
},
"author":{
"type":"array",
"items":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"firstName":{
"type":"string"
},
"lastName":{
"type":"string"
}
},
"required":[
"id",
"firstName",
"lastName"
]
}
},
"publisher":{
"type":"object",
"properties":{
"id":{
"type":"string"
},
"name":{
"type":"string"
},
"location":{
"type":"string"
}
},
"required":[
"id",
"name",
"location"
]
}
},
"required":[
"id",
"name",
"ISBN",
"price",
"author",
"publisher"
]
}
/Author:
get:
responses:
200:
body:
application/xml:
schema: authors-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<authors></authors>
application/json:
schema: authors-jsonschema
example: |
{
"authors" : ""
}
/{id}:
get:
responses:
200:
body:
application/xml:
schema: author-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<author></author>
application/json:
schema: author-jsonschema
example: |
{
"author" : ""
}
/Book:
post:
body:
application/xml:
schema: book-jsonschema
application/json:
schema: book-jsonschema
responses:
200:
body:
application/xml:
schema: book-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<book>
<price></price>
</book>
application/json:
schema: book-jsonschema
example: |
{
"book" : {
"price" : ""
}
}
get:
responses:
200:
body:
application/xml:
schema: books-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<book>
<price></price>
</book>
application/json:
schema: books-jsonschema
example: |
{
"book" : {
"price" : ""
}
}
/search:
get:
queryParameters:
name:
responses:
200:
body:
application/xml:
schema: books-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<book>
<price></price>
</book>
application/json:
schema: books-jsonschema
example: |
{
"book" : {
"price" : ""
}
}
/{id}:
get:
responses:
200:
body:
application/xml:
schema: book-jsonschema
example: |
<?xml version="1.0" encoding="UTF-8"?>
<book>
<price></price>
</book>
application/json:
schema: book-jsonschema
example: |
{
"book" : {
"price" : ""
}
}