«Как я перестал волноваться и стал отдавать метаданные restful API»

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

Поддержка такого ресурса (особенно в условиях, когда API активно развивается) — достаточно трудозатратное дело. При изменениях, приходится синхронизировать документацию с фактической реализацией и это напрягает. Синхронизация состоит из:

• Проверки, что вся существующая функциональность описана в документации
• Проверки, что всё описанное работает как заявлено в документации

Автоматизировать второй пункт предлагают ребята из стартапа apiary.io, они предоставляют возможность написать документацию на специальном предметно-ориентированном языке (DSL), а потом, при помощи прокси к вашему API, записать запросы, и периодически проверять, что всё, описанное соответствует действительности. Но в данном случае, вам всё ещё придется самим писать всю документацию, и это кажется лишним, потому что интерфейс вы, скорее всего, уже описали в коде.

Конечно же, универсального способа извлечь интерфейс в виде описания запросов и ответов из кода не существует, но если вы используете фреймворк, в котором есть соглашения по поводу маршрутизации и выполнения запросов, то такую информацию можно получить. Кроме того, существует мнение, что такое описание не нужно и клиент должен сам понять, как работать с REST API, зная только URL корневого ресурса и используемые media types. Но я не видел ни одного серьёзного публичного API, которое использует такой подход. 

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

Есть несколько вариантов: читайте продолжение в нашем блоге http://habrahabr.ru/company/dnevnik_ru/blog/174555/