Swagger: как объединить общие сведения из разных API

Я добавляю поддержку swagger 1.5.0 к существующему приложению java, которое реализует 20 + различных API REST и использует Джерси 1.17.1 с сканирование пакетов. Есть ли у кого-нибудь рекомендации по наилучшей практике? Например:

  • Должны ли определения swagger быть добавлены к каждому классу java или они могут быть
    добавлен в независимый файл(ы), чтобы не касаться каждого класса?
  • Для каждого API требуется тот же набор заголовков, который я подробно определил для первого класса с помощью @ApiImplicitParam. Вместо
    повторяя эту информацию для каждой операции каждого класса,
    есть способ применить его ко всем API?

1 ответ

  1. Существует множество способов интеграции swagger 1.5.X библиотеки (Примечание: 1.5.10 является последним) с приложением JAX-RS. Я предлагаю вам следовать схеме, как в swagger-petstore и разделить файлы на сегменты пути верхнего уровня, которые должны обеспечить логическую организацию.

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