Комментарии 18
Swagger делает то же самое.
Я просто оставлю это здесь:
@api
@api
Я не спорю что есть что то делающее то же самое
Но например зайдя в api функционал, скуден как по мне нет нормальной документации
Но например зайдя в api функционал, скуден как по мне нет нормальной документации
И вот так легким движением руки делается дублирование — указанное в @ApiDoc с вероятностью 146% будет расходиться с тем, что на самом деле происходит в коде. Поэтому для «своих» эта документация вредна — надежнее посмотреть в код, а для «чужих» — источник боли, страдания и унижения.
Главная проблема этих штук — генерация документации по API постфактум. То есть когда код уже написан. Это вроде здорово, но не для всех подходит.
Я в последнее время пришел к такому флоу:
1) мобильщики/фронтэндщики и бэкэндщики содятся обсуждать фичу и API которое им надо предоставить. Все решения записываются в доку в формате api blueprint (MSON — киллер фича, конкурентов которой я пока ненашел).
2) Мобильщики фронтэндеры садятся писать свою часть функционала и на время пока апишка не готова могут поднять mock-сервер сгенерированнй на основе документации.
3) бэкэндер может реализовать апишку и забрать схему респонсов скажем из документации (к сожалению парсера для php пока нет, приходится конвертить markdown в json средствами node.js и затем уже юзать, но это пока я парсер не допишу), и валидировать скажем в тестах на предмет соотвествия документации. Ну и опять же можно вместо прописывания урлов брать все из документации (по названию действий) и тогда можно тестами покрыть и функционал и соответствие документации которую ожидают от вас мобильщики/фронтэндеры.
Профит.
Я в последнее время пришел к такому флоу:
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.
Опять же повторюсь — это чисто мой случай.
В целом же api blueprint + mson как по мне поддерживать проще и удобнее чем гору аннотаций в контролерах. Да и читается оно приятно, и на сервак не попадет (апишки в моем случае приватные, документация так же, так что так удобнее и проще).
А ну и еще — я не использую таких вещей как JmsSerializer и прочие fos rest bundles (точнее последний я использую но только что бы не писать свой exception controller и прочие мелочи жизни), а в качестве DTO используются динамические штуки (массивы, stdClass, ect). Так что при использовании NelmioApiDocBundle дублирования происходит сильно больше чем при использовании MSON.
Опять же повторюсь — это чисто мой случай.
Ну скажем у меня код пишется постфакту после планирования того зачем этот метод вообще нужен.
Когда все решено то я описываю что он принимает и что отдает а потом уже пишу код который в итоге не расходится с документацией
Когда все решено то я описываю что он принимает и что отдает а потом уже пишу код который в итоге не расходится с документацией
Ну а у меня документация пишется вместе с планированием. То есть мы сначала обсуждаем фичу, потом пишем документацию. Сейчас к документации по апи планирую добавить еще фичаспеки.
Суть в том что контроллеры я обычно пишу в последнюю очередь, и это создает довольно большую задержку по времени, наличие возможности генерировать мок сервера по документации сильно упрощают в этом случае жизнь, а имплементация сначала слоя предметной области позволяет быстрее найти сценарии которые мы не обсудили (новые сценарии могут поменять API иногда, хотя это редко случается).
Суть в том что контроллеры я обычно пишу в последнюю очередь, и это создает довольно большую задержку по времени, наличие возможности генерировать мок сервера по документации сильно упрощают в этом случае жизнь, а имплементация сначала слоя предметной области позволяет быстрее найти сценарии которые мы не обсудили (новые сценарии могут поменять API иногда, хотя это редко случается).
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Автоматическая генерация API doc через Аннотации или как прийти к документированию API