Как вы документируете свои rest api?

Question

[Пума Тайланд]

К примеру написал я свой rest api, хочу дать его всем пользоваться, если ли какие то стандартные способы создания документации или гайды, кукбуки по созданию документации.

Comments

[Пума Тайланд]

Вот пример хорошо оформленного апи, хотелось бы cms для этого или же какой нибудь генератор красивых хтмлок
get.gaug.es/documentation/reference-listing/gauges/

Answer 1

[VaiMR]

К примеру en.wikipedia.org/wiki/Web_Application_Description_Language. А для себя (два разработчика, клиент и сервер) google docs выручает, чтобы не заморачиваться.

Answer 2

[Данила Штань]

apiary.io

Comments

[akhkharu]

Инвайтом можете поделиться?

[Данила Штань]

Могу, на какую почту?

Answer 3

[Wott]

Я считаю что REST APi должен очень простым и понятным, но действительно сложными представлениями я пока не рулил.

В качестве доки я обычно даю минимальный пример взаимодействия в котором комментирую необходимые действия и привожу должные ответы от сервиса. В принципе наверно можно найти тулзу которая приведет код примера к красивому html, но это скорее вопрос генерирования док вообще а не для api.

Answer 4

[Сергей Протько]

У меня все REST методы описываются через аннотации (Symfony 2) ну и потом по ним генерится документация. Добавить туда примеры с curl проблемы не составляет.

Comments

[Сергей Протько]

По сути можно оформить все в PHPDoc через маркдаун какой и потом генерить документацию. Так будет проще потом — поправили метод — документация сразу же обновилась.

Answer 5

[1nd1go]

Я вот спрашивал, может найдете что полезное для себя.