t1gor Aug 28 2017 at 18:15

Декларативное программирование в web-е

13 min

24K

Website development *PHP *Programming *XML *API *

+15

Comments 12

zloyusr Aug 28 2017 at 18:36

$result = (false === $data) ? ['status' => 'fail', 'code' => 12345] : ['status' => 'ok'];

Похоже, должно быть так

t1gor Aug 28 2017 at 18:38

Да, конечно. Спасибо, исправил.

Fedcomp Aug 28 2017 at 22:50

Почему бы сразу не создать тест который будет делать по сути тоже что и swagger ui но при этом быть более эффективной спецификацией?

t1gor Aug 29 2017 at 08:56

Как мне видится — Swagger UI больше для людей, а не для машин. Например для разработчиков, работающих над интеграцией стороннего (читай вашего) API.

Fedcomp Aug 29 2017 at 11:47

Я не могу сказать про php, но судя по всему статья в целом для web языков. Так вот, в ruby есть rspec_api_documentation, который прямо по тестам генерирует туже самую документацию. Только при этом она гарантированно синхронизирована с кодовой базой и гарантированно работает (иначе документация просто не соберется). Если для php такого инструмента нет, то стоит его написать вместо траты времени на лишнюю работу в виде декларативного описания апи которое уже описано кодом.

LbISS Aug 28 2017 at 22:51

Используем в нескольких проектах webapi2 + swashbuckle (генератор swagger-описания из XML документации C# проекта). Итого он еще и описания делает красивые из summary.
Мне кажется, мастхэв. Трудозатрат не стоит никаких, собирается и публикуется автоматически при билде, но сильно упрощает всё — работу внешних разработчиков, внутреннюю разработку и коммуникации фронта/бэка, тестирование, работу тех. писателей…
Но и заменой тестов это считать не стоит.

UFO just landed and posted this here

t1gor Aug 29 2017 at 09:02

В Swagger вроде только однотипные объекты, как коллекция. Да и в XML/XSD тоже (xs:sequence). В целом если нужен ключ — используйте поля/атрибуты вложенных элементов.

vintage Aug 29 2017 at 09:46

Tree — не более чем абстрактный формат сериализации дерева. Семантика узлов уже определяется языками. Ну то есть можно придумать какой-нибудь язык schema.tree, для описания других tree-языков. Что-то вроде:

$string \
$number \
$time \

$user user
    name $string
    age $number
    friends $user

$comment comment
    message $string
    author $user
    reply-to $comment

$article article
    title $string
    published $time
    author $user
    comments $comment

Примерно такое описание у нас было для моделей, по которым генерировался как серверный (/article/@123?fetch=comments/@), так и клиентский (domain.artcile(123).comments()) апи, так что в этих развесистых описаниях эндпоинтов не было никакой необходимости. При реализации протокола коммуникации (рест, вебсекеты, прц) совершенно не важно какие там модели есть на сервере, а при использовании моделей (пользователи, комментарии, статьи) совершенно не важны детали протокола.

UFO just landed and posted this here

t1gor Aug 30 2017 at 15:00

Что-то я потерял нить дискуссии… В статье я хотел рассказать не совсем об этом. А о том, как достаточно просто можно проверять входные данные для web сервисов. При этом описание стандартизовано и не зависит от реализации на конкретном языке программирования. При чем тут сериализация?

UFO just landed and posted this here

Only those users with full accounts are able to leave comments. Log in, please.