Определение Grails REST XML API

Question

Стремясь доставить хорошо документированное приложение, я ищу хороший способ описать REST API для пользователей моего приложения Grails.

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

Я потратил пару часов на поиск решения, предложенного другими пользователями Grails, но не нашел изящного решения, кроме рекомендации использовать WADL или WSDL 2.0

Это выглядит как хорошее направление, но должен быть простой способ сделать это в Grails.

Буду признателен за руководство по созданию REST API на основе объектов моей модели, желательно с возможностью фильтрации или управления открытыми полями, а также с хорошим графическим способом его представления (что-то вроде плагина XSD Eclipse). )

Спасибо! Guy

Answer 1

Я бы посоветовал избегать WADL или WSDL для документации API, вы можете увидеть этот вопрос, где я объяснил свои причины: Почему медленное поглощение WADL .

WADL или WSDL обычно используются для автоматической генерации клиентского кода, они не являются удобочитаемой документацией. Я не думаю, что WADL или WSDL очень полезны для пользователя, чтобы понять, как правильно использовать ресурсы.

Я предпочитаю старую добрую HTML-документацию, например, мне нравится, как twitter документировал свой API

Если вы настаиваете на автоматическом создании документации по ресурсам, я могу порекомендовать этот документ к сервисному документу ATOM . Многие REST Framework могут генерировать его автоматически на основе аннотаций ресурсов. (например, Apache Wink)