外部REST APIの記述のためのSwaggerおよびRAMLドキュメントのサポート
「RESTアダプタ」は、SwaggerまたはRAMLドキュメントのいずれかに記述されているREST APIを消費するためのサポートを提供します。
-
RESTful API Modeling Language (RAML): RESTful APIを記述する言語。 RAMLは、RESTful APIまたは実用的RESTful API(RESTの制約に全面的には従わないAPI)を記述するために必要な情報を提供します。 「RESTアダプタのトリガー・リソース構成ページ」を参照してください。
-
Swagger: RESTful Webサービスを記述、生成、消費およびビジュアル化するための仕様。 「Swaggerドキュメントを使用して記述された外部REST APIを使用するようにRESTアダプタを構成」を参照してください。
次の例では、Swagger 2.0のファイルを示しています。 このファイルには、主に2つのリソースが含まれています。
-
/Book。 このリソースには、getおよびpostメソッドに加え、/Book/{id}、/Book/helloおよび/Book/searchサブリソースが含まれています。 -
/Author。 このリソースには、getメソッドおよび/Author/{id}サブリソースか含まれています。
アダプタ・エンドポイント構成ウィザードで呼出し(アウトバウンド)「RESTアダプタ」を構成すると、リソースおよびサブリソースがビジネス・オブジェクトとして選択用に表示され、ビジネス・オブジェクトで実行する操作として選択するためのメソッドが表示されます。
「RESTアダプタ」接続を作成する場合は、「接続タイプ」フィールドで「Swagger定義URL」を選択し、「接続プロパティ」ダイアログの「接続URL」フィールドにURLを指定します。 「起動接続の接続プロパティの構成」を参照してください。
{
"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"
}
}
}
}
}
}
次の例では、RAMLのファイルを示しています。 このファイルには、サービスを使用するスキーマが含まれています。 このファイルには、主に2つのリソースが含まれています。
-
/Author。 このリソースには、getメソッドおよび/Author/{id}サブリソースか含まれています。 -
/Book。 このリソースには、getおよびpostメソッドに加え、/Book/{id}および/Book/searchサブリソースが含まれています。
アダプタ・エンドポイント構成ウィザードで呼出し(アウトバウンド)「RESTアダプタ」を構成すると、リソースおよびサブリソースがビジネス・オブジェクトとして選択用に表示され、ビジネス・オブジェクトで実行する操作として選択するためのメソッドが表示されます。
「RESTアダプタ」接続を作成する場合は、「接続タイプ」フィールドで「RAML定義URL」を選択し、「接続プロパティ」ダイアログの「接続URL」フィールドにURLを指定します。
#%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" : ""
}
}