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

Question

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

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

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

Спасибо

Answer 1

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

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

Из билета Jira ENUNCIATE-356 :

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

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

Answer 2

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

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