Как автоматизировать документирование API REST (реализация Джерси)

Я написал довольно обширный API REST, используя Java Jersey (и JAXB). Я также написал документацию с помощью Wiki, но это был полностью ручной процесс, который очень подвержен ошибкам, особенно когда нам нужно вносить изменения, люди склонны забывать обновлять вики.

От взгляда вокруг, большинство других REST API также вручную создают свою документацию. Но мне интересно, может ли это быть хорошим решением для этого.

Вещи, которые должны быть документированы для каждой конечной точки:

Имя службы
Категория
URI
Параметр
Типы параметров
Типы ответов
Схема типа ответа (XSD)
Примеры запросов и ответов
Тип запроса (Get/Put/Post/Delete)
Описание
Коды ошибок, которые могут быть возвращены

И тогда, конечно, есть общие общие вещи, такие как

Безопасность
Обзор REST
Обработка ошибок
Etc

Эти общие вещи прекрасно описывают один раз и не требуют автоматизации, но для самих методов веб-сервиса представляется весьма желательным автоматизировать его.

Я думал о возможностях использования аннотаций и написании небольшой программы, которая генерирует XML, а затем XSLT, который должен генерировать фактическую документацию в HTML. Имеет ли смысл использовать пользовательский XDoclet?

Любая помощь будет высоко оценена, Алан

Ответ 1

Swagger - прекрасный вариант. Это проект на GitHub, имеет интеграцию Maven и множество других возможностей, чтобы поддерживать гибкость.

Руководство по интеграции: https://github.com/swagger-api/swagger-core/wiki

Дополнительная информация: http://swagger.io/

Ответ 2

К сожалению, Даррель отвечает технически корректно, но это фокус-фокус в реальном мире. Это основано на идеале, о котором только некоторые согласны, и даже если вы были очень осторожны в этом, есть вероятность, что по какой-то причине вне вашего контроля вы не можете точно соответствовать.

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

Точка Achim о WADL хороша. Поскольку он существует, мы должны иметь возможность создать базовый инструмент для создания документации API.

Некоторые люди взяли этот маршрут, и была разработана таблица стилей XSL для преобразования: https://wadl.dev.java.net/

Ответ 3

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

РЕДАКТИРОВАТЬ Упоминание доступно под зонтиком github

Ответ 4

вам может быть интересна способность Джерси предоставлять так называемое WADL описание для всех опубликованных ресурсов в формате XML во время выполнения (генерируется автоматически из аннотаций). Это должно содержать уже то, что вам нужно для базовой документации. Кроме того, вы можете добавить дополнительный JavaDoc, хотя это требует большей конфигурации.

Пожалуйста, смотрите здесь: https://jersey.java.net/documentation/latest/wadl.html

Ответ 5

Даррель отвечает точно. Тип описания не должен предоставляться клиентам REST API, поскольку он заставит клиентского разработчика объединить реализацию клиента с текущей реализацией сервиса. Это то, к чему стремится ограничение гиперссылки REST.

Вы все равно можете разработать API, который описан таким образом, но вы должны знать, что результирующая система не будет реализовывать архитектурный стиль REST и поэтому не будет иметь свойства (esp. evolvability), гарантированные REST.

Возможно, ваш интерфейс может быть лучшим решением, чем RPC. Но имейте в виду, что именно вы строите.

Ян

Ответ 6

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

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

Какие типы носителей вы используете?

Также добавьте ссылку в RFC2616 в своих документах. Это должно объяснить любому потребителю, как взаимодействовать с вашим сервисом.

Ответ 7

Вы можете найти rest-tool. Он следует языковому агностическому подходу для написания спецификации, макетной реализации и автоматизированного модульного тестирования для API RESTful.

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

Если ваши услуги еще не полностью реализованы, но, к примеру, должны использоваться веб-интерфейсом, rest-tool обеспечивает мгновенное издевательство на описание услуги. проверка схемы содержимого (схема JSON) также может быть легко добавлена наряду с документацией, а также используется модульными тестами.