Самодокументируемый интерфейс REST

Question

У меня есть сервер на основе Rails, на котором запущено несколько служб REST, и веб-интерфейс на основе Rails, который взаимодействует с сервером с помощью ActiveResource. Этот же сервер используется другими клиентами (например, мобильными). Я должен сгенерировать документацию для интерфейса REST. Мне нужно предоставить URL службы, структуру ввода / вывода и структуру документа об ошибках для каждой службы.

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

Answer 1

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

Ознакомьтесь с выступлением Джона Мура для дальнейшего обсуждения на http://vimeo.com/20781278

Answer 2

Когда вы применяете архитектурный стиль REST, вам не нужно документировать свой интерфейс.

Контракт между клиентом и сервером определяется используемым типом носителя. Если вам нужна какая-либо другая дополнительная документация, выне RESTful.

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