Как стать автором
Обновить

Комментарии 18

Swagger делает то же самое.
Да, он делает тоже самое — НО!!!
Это JS и значи работы будет еще больше.
Nelmio — это готовый бандл который просто прочтет нужные каменты — а значит будет быстрее
+ его можно заекстендить и расширить /
Значит не на тот свагер зашел )))
сваггер он один, есть просто разные реализации парсеров форматов и прочей белеберды.
Я просто оставлю это здесь:
@api
Я не спорю что есть что то делающее то же самое
Но например зайдя в api функционал, скуден как по мне нет нормальной документации
И вот так легким движением руки делается дублирование — указанное в @ApiDoc с вероятностью 146% будет расходиться с тем, что на самом деле происходит в коде. Поэтому для «своих» эта документация вредна — надежнее посмотреть в код, а для «чужих» — источник боли, страдания и унижения.
147%, чтобы символичнее было
Если так думать обо всем то смысл тогда вообще делать документацию и писать какой либо код
Главная проблема этих штук — генерация документации по API постфактум. То есть когда код уже написан. Это вроде здорово, но не для всех подходит.

Я в последнее время пришел к такому флоу:

1) мобильщики/фронтэндщики и бэкэндщики содятся обсуждать фичу и API которое им надо предоставить. Все решения записываются в доку в формате api blueprint (MSON — киллер фича, конкурентов которой я пока ненашел).
2) Мобильщики фронтэндеры садятся писать свою часть функционала и на время пока апишка не готова могут поднять mock-сервер сгенерированнй на основе документации.
3) бэкэндер может реализовать апишку и забрать схему респонсов скажем из документации (к сожалению парсера для php пока нет, приходится конвертить markdown в json средствами node.js и затем уже юзать, но это пока я парсер не допишу), и валидировать скажем в тестах на предмет соотвествия документации. Ну и опять же можно вместо прописывания урлов брать все из документации (по названию действий) и тогда можно тестами покрыть и функционал и соответствие документации которую ожидают от вас мобильщики/фронтэндеры.

Профит.
Если гоборить о «interface first», то мы сразу создаем эндпойнты и апи-модели, так и документацию можем сразу сгенерировать, и сервер сразу поднять, при необходимости даже модели через рефлекшн заполнять. Плюс, что спорно конечно, но мне ужасно не нравится когда api документация и код разделены. Ну и в конце концов, так час-другой обсуждений и api frontend готов.
когда api документация и код разделены

А мне нравится, все в markdown, можно по дифам коммитов смотреть что поменялось в апишке за такой-то период. А если использовать эту самую документацию в функциональных тестах у нас нет проблем с тем что бы следить за тем что бы документация соотвествовала истене.
Еще добавлю…

В целом же api blueprint + mson как по мне поддерживать проще и удобнее чем гору аннотаций в контролерах. Да и читается оно приятно, и на сервак не попадет (апишки в моем случае приватные, документация так же, так что так удобнее и проще).

А ну и еще — я не использую таких вещей как JmsSerializer и прочие fos rest bundles (точнее последний я использую но только что бы не писать свой exception controller и прочие мелочи жизни), а в качестве DTO используются динамические штуки (массивы, stdClass, ect). Так что при использовании NelmioApiDocBundle дублирования происходит сильно больше чем при использовании MSON.

Опять же повторюсь — это чисто мой случай.
Главное что бы документация была! и без ошибок) Во всех подходах есть и минусы и плюсы. В вашем варианте мне особенно понравилась генерация интеграционных тестов апи. А валидацию входных моделей делаете на освное того же json, или?
Пока нет, ибо информации из документации не хватает что бы полноценно организовать валидацию (там только типы данных и обязательное ли поле), можно в теории организовать разбор запроса в DTO но это много кода.
Ну скажем у меня код пишется постфакту после планирования того зачем этот метод вообще нужен.
Когда все решено то я описываю что он принимает и что отдает а потом уже пишу код который в итоге не расходится с документацией
Ну а у меня документация пишется вместе с планированием. То есть мы сначала обсуждаем фичу, потом пишем документацию. Сейчас к документации по апи планирую добавить еще фичаспеки.

Суть в том что контроллеры я обычно пишу в последнюю очередь, и это создает довольно большую задержку по времени, наличие возможности генерировать мок сервера по документации сильно упрощают в этом случае жизнь, а имплементация сначала слоя предметной области позволяет быстрее найти сценарии которые мы не обсудили (новые сценарии могут поменять API иногда, хотя это редко случается).
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.