Автоматическая генерация остальных конечных точек с использованием Swagger для Java

Question

Передо мной была поставлена ​​задача найти лучший способ для большого API, разработанного с использованием jaxrs, документировать для третьих лиц. Код в настоящее время хорошо документирован с помощью Javadoc. Мой вопрос состоит в том, чтобы помочь определить лучший подход, основанный на моих исследованиях, и убедиться, что мы идем по правильному пути, поэтому я ищу входные данные, комментарии или дополнительные рамки для рассмотрения. Я уверен, что это общий случай использования, и у других будут похожие проблемы, и я действительно ценю любой вклад от других, кто имеет опыт работы с чванством и документацией.

У нас есть требования, которые:

• У нас нет огромного количества аннотаций, загромождающих код.
• Мы можем задокументировать возвращаемые типы, такие как вложенные объекты и их правильную структуру JSON.
• Мы можем указать заголовки, ссылки и метаинформацию (это означает, что нам нужен swagger 2.0, а не 1.2)
• Мы хотели бы свести к минимуму время и затраты, где это возможно, но при этом сохранить качественную документацию.
• Работает с JDK 8.

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

Документация Swagger JAXRS: Ссылка

Этот плагин maven работает во время сборки и может предоставить нам разумную документацию, основанную на существующих комментариях javadoc. Однако он не поддерживает Swagger 2.0, который может накладывать ограничения на описание заголовков в ответах, которые жизненно важны для нашего варианта использования. Он может подобрать остальные службы без необходимости аннотаций @Api или @ApiOperation, которые требует плагин Swagger Maven. Обновление этого для работы с Swagger 2.0 может быть существенной задачей.

Swagger Maven Плагин: Ссылка

Плагин создает документацию swagger во время сборки на основе аннотаций, а не комментариев. Это потребует от нас прохождения всего проекта и аннотирования с помощью @Api и @ApiOperation. Мы можем обойтись без некоторых аннотаций, относящихся только к базовым классам, но для любых описаний или названий конечных точек нам нужно будет добавить детали в сами аннотации. Многие из этих аннотаций кажутся дублированными, как, например, у нас уже есть @Get или @Post, но нам все еще нужно добавить @ApiOperation и описать параметры, которые уже описаны в javadoc. Недостатком является то, что это займет время, а также приведет к очень загроможденному виду кода.

Swagger Core: ссылка

Ядро Swagger работает во время выполнения, что означает, что мы не можем удалять комментарии из существующего Javadoc. Он легко расширяется, как и плагин Swagger Maven, и мы могли бы добавить нашего собственного читателя или правила для добавления ссылок и метаинформации (или использовать наши собственные существующие аннотации). Недостатком является то, что описания для каждого метода должны быть откуда-то, поэтому их нужно будет добавлять в (еще больше) аннотации, которые, вероятно, будут забыты при добавлении нового кода.

Enunciate: Ссылка

Enunciate не работает для нас, поскольку нам нужно иметь возможность использовать аналогичную инфраструктуру в.NET, а также он не поддерживает JDK 8 (пока).

Мои выводы пока

Доктору Сваггера Джакрса ближе всего удалось сделать все, что мы хотим. Основная проблема - отсутствие чванства 2.0. Мы должны быть в состоянии обновлять версии Swagger соответственно, как и другие проекты, которые будут задокументированы вместе (на разных языках). Вторым лучшим для нас является плагин Swagger Maven, как и с пользовательским бегуном, так как это время сборки, должна быть возможность каким-то образом получить доступ к существующим комментариям Javadoc и добавить их в созданный Swagger - мы, вероятно, можем обойтись без некоторые аннотации относятся к базовым классам и извлекают остальную часть (например, описания) из комментариев с помощью нашего специального ридера. Наконец, ядро ​​swagger на самом деле не отвечает нашим потребностям, так как нам потребуется гораздо больше аннотаций, которые дублируют существующий Javadoc.

С неизвестным временем, необходимым для обновления доклета Swagger для поддержки Swagger 2.0, я склоняюсь к плагину Swagger Maven с пользовательским ридером (любые советы о том, как читать комментарии javadoc, будут полезны!). Есть ли какие-то рамки или детали, которые я пропустил, что делает мой вывод неточным?

Answer 1

У каждого свои потребности, поэтому я не буду предлагать способы, которыми вы занимаетесь. Но вы определенно можете расширить проект swagger-maven-plugin, создав собственный анализатор, который будет обнаруживаться через SPI.

Это не тривиальная задача, но если вы к этому склоняетесь, то есть инфраструктура для ее поддержки. Пожалуйста, смотрите здесь: https://github.com/swagger-api/swagger-parser