Как документировать REST API на основе Symfony (аналогично изложению возможностей документации)

Если у меня есть сервис на основе REST, написанный на фреймворке Symfony [symfony-project.org] (т. е. PHP), существуют ли какие-нибудь достойные инструменты/фреймворки, которые будут анализировать мой код и генерировать документацию по API?

Платформа enunciate на основе Java имеет возможности документирования, аналогичные тем, что мне нужны, вы можете просмотреть пример здесь: http://enunciate.codehaus.org/wannabecool/step1/index.html.

Я понимаю, что предпосылка сервисов на основе REST должна быть очевидной, однако я искал что-то, что могло бы сгенерировать эту документацию для меня без необходимости вручную записывать все мои конечные точки, поддерживаемые форматы, образец вывода и т. д.

Спасибо


person Dominic    schedule 03.05.2010    source источник


Ответы (2)


Не уверен, что вы уже видели Swagger. Кажется, у них есть совместимая с PHP версия, хотя я не могу за это поручиться. лично. Он выполняет некоторую автоматическую генерацию документации API, сравнимую с enunciate, хотя похоже, что для этого требуется тяжелая ручная документация с помощью комментариев PHP. При этом я думаю, что ручные усилия будут такими же или меньшими, чем создание ваших собственных через вики-страницы, а результат будет намного, намного лучше.

Как факт, похоже, что Enunciate имеет неопределенные планы в конечном счете< /em> поддерживает другие платформы, но соответствующий тикет Jira в настоящее время Открыть в ожидании спонсора, который возьмет на себя работу.

Из заявки Jira ENUNCIATE-356:

Первым шагом к поддержке других языков является отделение модели Enunciate от модели Java. Эта работа отслеживается и регистрируется по адресу ENUNCIATE-584. К сожалению, он так и не вышел из фазы расследования из-за того, насколько он тяжелый. Если не будет найден спонсор для работы, я не ожидаю, что в ближайшее время возьму на себя такую ​​тяжелую нагрузку.


Изменить:
Найдено похожий вопрос, где кто-то упоминает проект GitHub, посвященный Swagger+Symfony2. Этот другой вопрос тот же, но без дополнительных Информация.

person Patrick    schedule 26.09.2012
comment
Примечание: NelmioApiDocBundle предназначен для Symfony 2. - person j0k; 27.09.2012
comment
@ j0k Ах, да. Отмеченный. Спасибо! - person Patrick; 27.09.2012

Насколько мне известно, нет способа автоматизировать документирование типов носителей.

Если вы используете такой тип мультимедиа, как XHTML, поисковый робот, такой как карта сайта Google, может дать полезные результаты. чтобы показать отношения между вашими ресурсами.

person Darrel Miller    schedule 03.05.2010