Swagger
斯瓦格 是用于定义 REST API 的开放式规范。
斯瓦格 文档是与基于 SOAP 的 Web Service 的 WSDL 文档等效的 REST API。
斯瓦格 文档指定 REST API 中可用资源的列表以及可对这些资源调用的操作。 斯瓦格 文档还指定了操作的参数列表，包括参数的名称和类型，参数是必需参数还是可选参数，以及这些参数的可接受值的相关信息。 此外， 斯瓦格 文档还可以包含 JSON 模式 (用于描述发送到 REST API 中的操作的请求主体的结构) ，并且 JSON 模式 (用于描述从操作返回的任何响应主体的结构)。
Swagger 文档必须为含 .json 文件扩展名的 JSON 格式或者为含 .yaml 或 .yml 文件扩展名的 YAML 格式。
IBM® Integration Bus 支持版本 2.0 的 斯瓦格 规范。 有关 斯瓦格的信息，请参阅 斯瓦格。 有关 斯瓦格 规范的 V2.0 的信息，请参阅 Swagger RESTful API 文档规范版本 2.0。
提供了一系列第三方工具供您与 斯瓦格 文档配合使用:
- 斯瓦格 编辑器
- 通过提供 斯瓦格 文档以及生成的 REST API 定义的并排视图，帮助您从 Web 浏览器构建 斯瓦格 文档。 构建 斯瓦格 文档后，可以下载该文档以与 IBM Integration Bus配合使用。 有关更多信息，请参阅 GitHub: Swagger 编辑器。
- 斯瓦格 UI
- 允许您从任何 Web 浏览器对使用 斯瓦格 定义的 REST API 进行可视化和测试。 内置的测试功能使您能够指定该 REST API 中定义的操作的输入、从 Web 浏览器中调用该操作以及检查调用该操作的结果。 有关更多信息，请参阅 GitHub: Swagger UI。
- 斯瓦格 代码生成
- 从 REST API 的 斯瓦格 文档中生成各种语言 (包括 Java™， Objective-C ， PHP 和 Python) 的软件开发包 (SDK)。 产生的 SDK 可用于将对该 REST API 中的操作进行的调用嵌入到以某种受支持语言编写的软件程序中，而不必处理底层 HTTP 传输。 有关更多信息，请参阅 GitHub: Swagger 代码生成器。
大部分 斯瓦格 工具都接受 斯瓦格 文档作为指向 HTTP 服务器上托管的 斯瓦格 文档的 URL。 将 REST API 部署到 IBM Integration Bus时，会通过 HTTP 发布 斯瓦格 文档，以供您与 斯瓦格 工具配合使用。 斯瓦格 文档的方案，主机和端口号详细信息将自动更新为与正在运行的 REST API 的详细信息相匹配，以便可以使用 斯瓦格 来调用正在运行的 REST API。
IBM Integration Bus 对 斯瓦格 文档施加一些限制，请参阅 Swagger 文档的限制。
要查看 斯瓦格 文档的示例，请参阅 Swagger petstore。
以下 斯瓦格 文档的副本 <install root>/server/sample/restapis/swagger.json 随产品安装一起提供。
{
"swagger": "2.0",
"basePath": "/customerdb/v1",
"info": {
"title": "Customer Database",
"description": "This is the customer database sample Swagger document included with IBM Integration Bus.",
"version": "1.0.0"
},
"definitions": {
"Customer": {
"properties": {
"id": {
"type": "integer"
},
"firstname": {
"type": "string"
},
"lastname": {
"type": "string"
},
"address": {
"type": "string"
}
},
"required": [
"firstname",
"lastname",
"address"
]
}
},
"tags": [
{
"name": "customers",
"description": "Operations on customers in the customer database"
}
],
"paths": {
"/customers": {
"get": {
"operationId": "getCustomers",
"summary": "Get all customers from the database",
"parameters": [
{
"name": "max",
"in": "query",
"description": "Maximum number of customers to get from the database",
"required": false,
"type": "integer"
}
],
"responses": {
"200": {
"description": "An array of customers from the database",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Customer"
}
}
}
},
"tags": [
"customers"
]
},
"post": {
"operationId": "addCustomer",
"summary": "Add a customer to the database",
"parameters": [
{
"name": "body",
"in": "body",
"description": "The customer to add to the database",
"required": true,
"schema": {
"$ref": "#/definitions/Customer"
}
}
],
"responses": {
"200": {
"description": "If the customer was successfully added to the database"
}
},
"tags": [
"customers"
]
}
},
"/customers/{customerId}": {
"get": {
"operationId": "getCustomer",
"summary": "Get a specified customer from the database",
"parameters": [
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer to get from the database",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "The specified customer from the database",
"schema": {
"$ref": "#/definitions/Customer"
}
}
},
"tags": [
"customers"
]
},
"delete": {
"operationId": "deleteCustomer",
"summary": "Delete a specified customer from the database",
"parameters": [
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer to delete from the database",
"required": true,
"type": "integer"
},
{
"name": "Authorization-Key",
"in": "header",
"description": "Provide the authorization key that permits the customer to be deleted from the database",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "If the customer was successfully deleted from the database"
}
},
"tags": [
"customers"
]
}
}
}
}