Как сгенерировать swagger документацию с java

219

13 апреля 2018, 18:13

Всем привет!

Начинаю разбираться с Restful сервисами и сейчас возникла потребность написать документацию на swagger. Посмотрел много туториалов но ключевого для себя так и не понял.

В java классах я использую аннотация @Api и методах @ApiOperation и @ApiResponses, которые описывают поведение моих сервисов. Сама документация описывается в json файле, который можно будет отдать на swagger editor и посмотреть что получилось в итоге и если нужно то протестировать.

Возникает вопрос: генерировать это json или yaml файл я должен сам вручную, или же существует решение проще, с помощью тех java классов, которые я пометил аннотациями swagger. Может какая то тулза или сервис. Потому что если я его буду писать вручную, то какой смысл тогда от аннотаций.

Answer 1

Генерацию спецификации API по аннотациям классов и методов можно автоматизировать. В этом репозитории есть примеры автоматической генерации спецификации для многих комбинаций технологий. Во всех случаях приложение начинает отдавать спецификацию по заданному урлу (например, /api-docs.json). Это можно скомбинировать со swagger-ui, который по этой спецификации построит UI со списком методов и возможностью вызвать их.