Мне поставили задачу найти лучший способ документирования большого 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 не работает для нас, поскольку нам нужно иметь возможность использовать аналогичную структуру в .NET, а также она не поддерживает JDK 8 (пока).
Мои выводы на данный момент
Доклет swagger jaxrs был самым близким к тому, чтобы делать все, что мы хотели до сих пор. Основная проблема - это отсутствие чванства 2.0. Нам нужно иметь возможность обновлять версии swagger соответственно, как и другие проекты, которые будут документироваться вместе (на разных языках). Вторым лучшим для нас является плагин Swagger Maven, как и в случае с пользовательским раннером, поскольку это время сборки, должно быть возможно каким-то образом получить доступ к существующим комментариям javadoc и добавить их в созданный swagger - мы, вероятно, сможем уйти с рук некоторые аннотации относятся к базовым классам, а остальные (например, описания) извлекаются из комментариев с помощью нашего настраиваемого считывателя. Наконец, ядро swagger на самом деле не отвечает нашим потребностям, так как нам понадобится гораздо больше аннотаций, которые дублируют существующий javadoc.
С неизвестным временем, необходимым для обновления документа swagger для поддержки swagger 2.0, я склоняюсь к плагину swagger maven с настраиваемым ридером (любые советы о том, как читать комментарии javadoc оттуда, были бы полезны!). Есть ли какие-то рамки или детали, которые я упустил, что делает мой вывод неточным?
