Генерация документации REST-API из юнит-тестов

Я хочу автоматически задокументировать мой REST-API. Я знаю, что для этого есть много инструментов, но я хочу создать документацию из моих модульных тестов.

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

Я уже нашел два проекта с таким подходом, doctester и testdoc4j. Оба не удовлетворяют мои потребности. Полученная документация не объединяет счастливый путь и пути ошибок.

Какие инструменты вы используете и можете ли вы предложить какой-нибудь хороший?

Приветствия.

Редактировать:

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

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

Источник

4 ответа

Не уверен, что вы уже нашли что-то для этого, но Spring RestDocs делает именно то, о чем вы здесь спрашиваете.

https://spring.io/projects/spring-restdocs

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

Источник

Недавно я провел небольшое исследование на эту тему и решил использовать бесплатную версию Miredot, потому что это единственный инструмент, который удовлетворял моим требованиям:

  1. Не нуждается в дополнительных аннотациях. Вся информация извлекается из JavaDoc
  2. Может обрабатывать JAX-RS, а также аннотации Spring
  3. Простая интеграция Maven

Miredot автоматически генерирует документацию на основе HTML при запуске mvn test

Источник

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

Руководство по интеграции: Swagger-Core Wiki

Больше информации: здесь

Источник

Возможно, вы хотите, чтобы BDD Framework? Например:

Источник
Другие вопросы по тегам