ASP.NET web api: документирование/указание службы

Я смотрел asp.net Web Api, и мне нравится простота реализации практического веб-сервиса.

Однако, как я могу документировать/специфицировать интерфейс реализованной службы? Например, есть ли какая-либо спецификация, которую я могу передать или создать для Java-парня без фона .NET, который позволит ему легко звонить и потреблять услугу? Что я могу дать парню javascript?

В идеале, я бы хотел использовать SOAP/XSD или что-то в этом роде (легко десериализовать с красиво типизированными объектами) для java-парня, сохраняя при этом службу, вызываемую из веб-браузера (т.е. поддерживает не-crufy JSON).

Update

Стоит отметить, что, поскольку я изначально опубликовал этот вопрос, я обнаружил ServiceStack, который более естественно относится к этому вопросу; поддерживая JSON, SOAP и WSDL из коробки для той же услуги, что и клиент. Если вы действительно хотите SOAP + JSON, это может быть лучше, чем ASP.NET Web Api.

Ответ 1

Обновить март 2016

Прошло некоторое время с тех пор, как на это был дан ответ, и инструментарий для документирования любого API Rest API прошел много. В настоящее время мы оцениваем Swagger 2.0, теперь выпадающий на Open Api Инициатива, RAML и API Blueprint.

Для проектов WebAPI существует инструмент Swashbuckle, который автоматически создает документацию формата Swagger (Open API).

Формат для документирования службы REST:

Существуют некоторые попытки структурирования и стандартизации описания служб REST:

Язык описания веб-приложений (WADL)
Язык описания веб-сервисов 2.0 (WSDL 2.0)

Я думаю, справедливо сказать, что ни один из двух подходов выше не имеет очень широкого применения, но 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.

Ответ 2

Вы можете использовать интерфейс IApiExplorer и ApiExplorer, чтобы создать страницу справки для службы Web Api. На этой странице справки будут описаны методы REST, выставленные вашей службой, поэтому любой разработчик, который понимает, как работает REST, сможет использовать его (независимо от языка). Пожалуйста, прочитайте ниже ссылки для деталей и образцов: