WSDL в OpenAPI: REST-фасад для SOAP-сервиса

Когда SOAP-сервис нужно открыть для фронтенда, мобильного приложения или партнёров через REST-шлюз, начинают с описания фасада в OpenAPI. Механическую часть — операции и структуры данных — можно получить из WSDL автоматически.

Как преобразовать

1. Откройте описание в редакторе WSDL (из проекта, если типы вынесены в отдельные XSD).
2. Выберите Файл → Преобразовать в → OpenAPI — REST-фасад.
3. Откройте результат в редакторе OpenAPI — справа сразу появится документация в стиле Swagger UI.

Что получается

• Каждая операция portType — путь POST /{имя операции} с operationId и тегом интерфейса.
• Входное и выходное сообщения — тела запроса и ответа; их элементы и типы из wsdl:types и подключённых XSD переводятся в схемы components/schemas.
• Ошибки (fault) — ответ 500 со схемой ошибки.
• soapAction сохраняется в расширении x-soap-action — пригодится при настройке шлюза.
• Адреса сервиса (soap:address) — servers.

Чего автоматическое преобразование не сделает

Результат — RPC-стиль: каждая операция остаётся «глаголом». Ресурсный REST (GET /orders/{id} вместо POST /GetOrder), коды ответов 404/409, пагинация и идемпотентность проектируются отдельно — это решение о дизайне API, а не перевод формата. Используйте черновик как точку отсчёта: структуры данных уже готовы, осталось переложить операции на ресурсы.

О различиях подходов — в статье «REST и SOAP: что для чего».

Пример

Операция GetOrder с входным сообщением GetOrderRequest (элемент с orderId) и выходным GetOrderResponse превращается в:

paths:
  /GetOrder:
    post:
      operationId: GetOrder
      tags: [OrderPort]
      x-soap-action: urn:example:orders:GetOrder
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: "#/components/schemas/GetOrderRequest"}
      responses:
        "200":
          description: Ответ
          content:
            application/json:
              schema: {$ref: "#/components/schemas/GetOrderResponse"}

Вопросы и ответы

Как превратить RPC-методы в ресурсы? Сгруппируйте операции по сущностям: GetOrder, CreateOrder, CancelOrder → GET /orders/{id}, POST /orders, POST /orders/{id}/cancel. Схемы из черновика переиспользуйте, убрав обёртки запросов.

Типы из внешних XSD учитываются? Да, если WSDL и схемы лежат в одном проекте — импорт разрешается по путям, типы попадают в components/schemas.