Ответ 1
Обновить март 2016
Прошло некоторое время с тех пор, как на это был дан ответ, и инструментарий для документирования любого API Rest API прошел много. В настоящее время мы оцениваем Swagger 2.0, теперь выпадающий на Open Api Инициатива, RAML и API Blueprint.
Для проектов WebAPI существует инструмент Swashbuckle, который автоматически создает документацию формата Swagger (Open API).
Формат для документирования службы REST:
Существуют некоторые попытки структурирования и стандартизации описания служб REST:
Я думаю, справедливо сказать, что ни один из двух подходов выше не имеет очень широкого применения, но WADL действительно выглядит как красивый сжатый формат - быстрый XSLT поверх, и это может быть хороший читаемый человеком формат. Там много примеров WADL для некоторых известных API на сайте apigee github здесь.
При попытке найти подходящий формат документации я склонен искать "вдохновение" у других... Apigee делает много исследований в этой области и имеет это в качестве документации для одного из своих API здесь или посмотрите на социальный график Facebook api здесь.
Примеры в значительной степени согласуются с рекомендацией здесь
Как сделать автоматический документ:
Использование .NET: есть хороший пример автоматического создания страницы справки WebApi здесь. Логическим продолжением этого примера может быть получение его версии WADL, также...
Использование Java: Jersey - это инструмент, используемый в сообществе Java для автоматического создания WADL.
Что нужно поделиться с другими разработчиками:
Ваш Javascript-парень, скорее всего, захочет получить руководство, подобное Facebook и apigee; давая разработчикам примеры ресурсов, URL-адресов, кодов ответов и т.д. Самое главное здесь будет поддерживать JSON в качестве основного типа контента, который будет самым легким для него/ее потреблять и работать далеко.
Ваш Java-разработчик также хотел бы получить руководство, но также теоретически им может быть предоставлен пример XSD для любых представлений XML ресурсов, которые вы отправляете/потребляете (при условии, что они делают запрос "Content-Type: appplication/xml" ), Эта может помочь им создавать классы прокси и т.д. Преобразователи JSON в Java и .NET доступны в Интернете и, учитывая примеры ресурсов в вашем руководстве, они должны просто использовать один из этих типов сервисов для быстрого создания прокси. Создать Java-класс из JSON?.
Если у вас обязательно должно быть автоматическое обнаружение, автоматическое создание прокси-сервера и т.д., вам может потребоваться выбор и конечных точек REST и SOAP (с WSDL) - вопрос здесь: Генератор объектов ProST Pro.