Я смотрю на Spring REST Docs и задаюсь вопросом, есть ли у него возможность опрашивать методы @RestController для создания базовой документации, описывающей Rest API.
Spring REST Docs ориентирован на тестирование и намеренно не использует подход @RestController к самоанализу. В документации по REST API описаны HTTP-запросы и ответы. Благодаря тестированию и работе с настоящими или фиктивными HTTP-запросами и ответами, REST Docs гарантирует, что то, что вы документируете, будет тем, с чем будут иметь дело пользователи вашего API.
Проблема с @RestController методами самоанализа в том, что это всего лишь небольшой кусочек головоломки. Когда получен HTTP-запрос, он проходит через фильтры, перехватчики, преобразование HTTP-сообщений и т. Д., Прежде чем достигнет вашего контроллера. То же самое верно и в обратном порядке, когда отправляется ответ. Без полного понимания всего, что происходит до вызова вашего контроллера, и всего, что происходит после его возврата, документация может оказаться неточной.
- это подход Spring RestDocs для запуска ваших интеграционных тестов в тестовой среде, а затем копирования сгенерированных документов / фрагментов в war, чтобы их можно было просмотреть в среде Prod.
Верный. Документация создается один раз во время сборки, а затем обычно подается в виде статических файлов из вашего приложения. Подробная информация о том, как это сделать с помощью Spring Boot: включен в документацию.
Этот подход имеет то преимущество, что ни один код, участвующий в создании документации, не работает в производственной среде. Это уменьшает объем вашего приложения и исключает возможность того, что код, генерирующий документацию, вызовет проблемы в производственной среде. Я считаю, что вы можете использовать аналогичный подход с инструментами Swagger, ориентированными на код, но, по моему опыту, люди это делают необычно.
person
Andy Wilkinson
schedule
14.10.2016
