Введение

WSDL (Web Services Description Language) — XML-формат описания веб-сервисов: какие операции предоставляет сервис, какие сообщения он принимает и возвращает, по какому протоколу и по какому адресу к нему обращаться. Чаще всего WSDL описывает SOAP-сервисы — их по-прежнему используют банки, государственные системы, ERP и интеграционные шины.

Наиболее распространена версия WSDL 1.1; ей и посвящена эта документация. Отличия WSDL 2.0 — на странице «Практика и WSDL 2.0».

Из чего состоит описание

WSDL разделяет абстрактную часть — что делает сервис — и конкретную — как и где к нему обращаться:

Элемент	Часть	Назначение
types	Абстрактная	Типы данных — обычно схема XSD
message	Абстрактная	Сообщение: набор частей (part)
portType	Абстрактная	Интерфейс: набор операций с входными и выходными сообщениями
binding	Конкретная	Привязка интерфейса к протоколу и формату (SOAP, HTTP)
service / port	Конкретная	Адрес, по которому доступна привязка

Такое разделение позволяет предоставить один и тот же интерфейс по разным протоколам и адресам.

Первый пример

Сервис курсов валют: операция GetRate принимает код валюты и возвращает курс.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="RatesService"
    targetNamespace="http://example.com/rates"
    xmlns:tns="http://example.com/rates"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <xs:schema targetNamespace="http://example.com/rates" elementFormDefault="qualified">
      <xs:element name="GetRate">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="currency" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="GetRateResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="rate" type="xs:decimal"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </wsdl:types>
  <wsdl:message name="GetRateRequest">
    <wsdl:part name="parameters" element="tns:GetRate"/>
  </wsdl:message>
  <wsdl:message name="GetRateResponse">
    <wsdl:part name="parameters" element="tns:GetRateResponse"/>
  </wsdl:message>
  <wsdl:portType name="RatesPortType">
    <wsdl:operation name="GetRate">
      <wsdl:input message="tns:GetRateRequest"/>
      <wsdl:output message="tns:GetRateResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="RatesSoapBinding" type="tns:RatesPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="GetRate">
      <soap:operation soapAction="http://example.com/rates/GetRate"/>
      <wsdl:input><soap:body use="literal"/></wsdl:input>
      <wsdl:output><soap:body use="literal"/></wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="RatesService">
    <wsdl:port name="RatesPort" binding="tns:RatesSoapBinding">
      <soap:address location="https://api.example.com/rates"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Так выглядит запрос к этому сервису (конверт SOAP 1.1):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:r="http://example.com/rates">
  <soapenv:Body>
    <r:GetRate>
      <r:currency>USD</r:currency>
    </r:GetRate>
  </soapenv:Body>
</soapenv:Envelope>

В редакторе

Редактор WSDL показывает код и схему «интерфейсы → привязки → сервисы», проверяет синтаксис по мере ввода, а типы из wsdl:types — как схему XSD. Схемы можно не встраивать, а подключать из соседних файлов проекта (xs:import, wsdl:import) — ссылки разрешаются по дереву папок, Ctrl+клик открывает файл.

Разделы документации

• Структура документа — definitions, types, message, portType, binding, service, import.
• Операции — четыре вида операций, сообщения об ошибках.
• Привязка SOAP — стили document и rpc, literal и encoded, заголовки и ошибки.
• Привязки HTTP и MIME — вызовы GET/POST и вложения.
• Практика и WSDL 2.0 — стиль document/literal wrapped, совместимость и отличия новой версии.