@denikeweb
Freelancer, creative developer

Документация к SOAP API. Нужна ли она и справедливо ли возражение о том, что WSDL достаточно?

Добрый вечер, пользователи Тостера.

Я хотел бы услышать ваше мнения по поводу ситуации, описанной ниже.

Есть компания А - бизнес, компания Б - разработчики БД для бизнеса и приложений для кассиров бизнеса, компания В - разработчик веб-сайта для компании А, который должен получить содержимое БД, которую сейчас использует бизнес.

Я программист, фрилансер, работаю с компанией В и делаю всю программную часть сайта. И сайт должен выгрузить содержимое БД, которую разрабатывает компания Б. Программисты компании Б должны были написать API для общения наших двух систем.

Спустя 2 недели после дедлайна, они сделали API, но без документации. Менеджер компании Б сказал, что WSDL должно быть достаточно для понимания. Я не согласился и попросил предоставить хотя бы пример кода. Потом это переросло в спор.

Немного сути АПИ: 2 запроса на получение данных. Второй имеет 3 параметра: shopID (суть понятна из названия, значение получаем с первого запроса), дата и булевый параметр. У меня не получилось угадать со вторыми параметрами. Да, спустя 6 часов переговоров я получил кусок кода и подстеб со стороны менеджера из-за того, что я не смог угадать параметры.

После дискуссия продолжилась:
>>> для АПИ пишется документация.
вы не можете найти документацию на SOAP ? я не понимаю зачем вы у меня требуете то что, лежит в свободном доступе и разрабатывалось не нами.

Нет, в принципе, если бы я смог выполнить свою работу, то я бы не парился и не писал бы этот текст. Просто фишка в том, что в итоге то API оказалось неполноценным и нам еще предстоит совместная работа. Собственно вопрос в том, адекватно ли возражение со стороны менеджера компании Б, приведенное выше, или я должен был получить документацию?

P.S.: неправильно предположив значения параметров (name=dt type=xs:dateTime и name=firstTime type=xs:boolean) я не получил ожидаемого результата
  • Вопрос задан
  • 1769 просмотров
Решения вопроса 2
@asdz
Ну обычно на wsdl натравливается парсер который строит классы клиента. Технически это позволяет уже общаться с сервисом. Но все таки этого может быть недостаточно - надо же знать какая функция для чего нужна. WSDL это все таки не документация, а просто описание, метаданные.
Ответ написан
Комментировать
pi314
@pi314
Президент Солнечной системы и окрестностей
Послать такого менеджера нужно на... курсы по WSDL, в частности, чтоб про "wsdl:documentation" узнал и устыдился. А вообще, типы параметров, определенные WSDL - это, как бы, одно, а вот их предназначение - совсем другое. Уважающие себя разрабы ко второму не только пишут доку в WSDL, но могут даже нарисовать UML и написать текст с примерами, если логика интерфейса требует этого ввиду своей нетривиальности.

P.S. Впрочем, самоуважение, как и профессионализм, не относятся к ключевым скилам среднестатистического современного менеджера :)
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 5
Fesor
@Fesor
Full-stack developer (Symfony, Angular)
WSDL достаточно, по нему генерируется код, в нем есть вообще все все все что нужно для работы с API. Документация нужна только если у вас море методов и все они делают какие-то сложные вещи не очевидные из названий.
Ответ написан
xmoonlight
@xmoonlight
https://sitecoder.blogspot.com
WSDL - достаточен для понимания диалога.
Для отладки используйте XMLSpy
Ответ написан
@liff
PHP >= 5.4, 7 + PostgreSQL + JS + EmberJs +++
WSDL достаточно IMHO.

P.S ShopId не ЯД - ли))
Ответ написан
Ashlst
@Ashlst
Фанат эстетики и красивых решений.
Можно использовать SoapUI,он позволяет сгенерировать документацию по wsdl-файлу.Довольно удобно если много кода.
Ответ написан
Комментировать
@Gokudera
java developer
Мне вот интересно ТЗ то было у тех кто создавал API?

ИМХО: ТЗ + WSDL - уже 85% документации.

WSDL достаточно IMHO.
Ну это если WSDL нормальная.
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Похожие вопросы