ОК, я знаю, что есть PhpDocumentor для генерации документации из кода php. Кажется, он долгое время не обновлялся (но, возможно, они полагают, что в основном его функции завершены).
Хотя это может быть полезно для документирования вещей для других программистов, оно не очень подходит для документирования внешнего «API» веб-службы. То есть, если у меня есть хороший структурированный проект MVC, PhpDocumentor может отлично подойти для документирования всех моделей и внутренних библиотек и тому подобного для других разработчиков этого проекта, но как мне документировать веб-сервис, который он предоставляет?
Я думаю, что вы могли бы документировать методы на контроллерах, используя такие теги, как:
/**
@service /device/add
@access POST
@return JSON
*/
, который в сгенерированных документах показывает, что вам нужно выполнить запрос POST, он возвращает данные JSON и URL-адрес для доступа к ним http://whatever.com/device/add. Очевидно, что для документации будет определен глобальный файл конфигурации, который определяет, что базовый URL предназначен для этих сервисных вызовов.
На данный момент я думаю, что сам реализую что-то, используя отражение в блоках phpdoc (или используя аннотации с библиотекой addendum), и буду иметь документы, доступные динамически прямо в приложении.