Swagger is the original name of the OpenAPI Specification (OAS): a JSON or YAML document that describes a REST API - its paths, operations, parameters, request / response schemas and security. Swagger 2.0 = OpenAPI 2.0; OpenAPI 3.x is the current spec (the Swagger name lives on in the tools: Swagger UI, Swagger Editor, Swagger Codegen). BAW consumes Swagger 2.0 (BAW 18+) and OpenAPI 3.0 (BAW 20.0.0.2+) files to generate REST external services, and it publishes its own APIs as Swagger (/bpm/docs, /ops/docs).
Minimal file that BAW imports without complaint (Swagger 2.0):
{
"swagger": "2.0",
"info": { "title": "Customer API", "version": "1.0" },
"host": "api.example.com", "basePath": "/v1", "schemes": ["https"],
"securityDefinitions": { "basicAuth": { "type": "basic" } },
"paths": {
"/customers/{id}": {
"get": {
"operationId": "getCustomer",
"parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ],
"responses": { "200": { "description": "ok", "schema": { "$ref": "#/definitions/Customer" } } },
"security": [ { "basicAuth": [] } ]
}
}
},
"definitions": {
"Customer": { "type": "object", "properties": { "id": {"type": "string"}, "name": {"type": "string"}, "creditLimit": {"type": "number"} } }
}
}Rules for a file that generates clean BAW artifacts: give every operation an operationId (becomes the operation name), name every schema (anonymous objects get ugly generated names), avoid property names that clash with existing business objects (NameValuePair, Record), use only application/json, and keep the host out of the decision - BAW's Server definition overrides it per environment. Validate the file in the Swagger Editor (editor.swagger.io) before importing; in Process Designer: External Service > New > Import from file / URL, then map the operations in a service flow with the generated business objects.
References