Comments 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 иногда, хотя это редко случается).
Sign up to leave a comment.
Автоматическая генерация API doc через Аннотации или как прийти к документированию API