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

[zloyusr]

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

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

[t1gor]

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

[Fedcomp]

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

[t1gor]

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

[Fedcomp]

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

[LbISS]

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

[t1gor]

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

[vintage]

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()) апи, так что в этих развесистых описаниях эндпоинтов не было никакой необходимости. При реализации протокола коммуникации (рест, вебсекеты, прц) совершенно не важно какие там модели есть на сервере, а при использовании моделей (пользователи, комментарии, статьи) совершенно не важны детали протокола.

[t1gor]

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