Создать статический API-документ

Question

Мне нужно хранить статичные сгенерированные файлы api json в нашем git-репозитории, чтобы легко отслеживать изменения API. Подобно этому http://petstore.swagger.wordnik.com/api/api-docs/user

Я подключил плагин Maven https://github.com/kongchen/swagger-maven-plugin

в проект, и он генерирует файлы *.json для API. Но порядок API и свойства время от времени различаются. Таким образом, файлы *.json модифицируются без каких-либо изменений API (только в другом порядке).

Затем я указал параметр "положение" для каждого

@Api,
@ApiOperation
@ApiModelProperty

аннотаций,

и это в основном помогает. но есть некоторые службы, которые возвращают классы org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput и javax.ws.rs.core.Response, и свойства для этих классов все еще находятся в случайном порядке. Итак, я переопределил json представление этих классов с помощью /swagger-overriding-models.json

И теперь работает нормально. Я просто бродил, может быть, это не самый лучший способ, и есть некоторые другие возможности, чтобы файлы api json генерировались в предсказуемом порядке, без путаницы с "позицией" и переопределением модели?

Answer 1

Гарантировать заказ не так просто. Отражение Java не гарантирует упорядочение при использовании отражения - http://docs.oracle.com/javase/8/docs/api/java/lang/Class.html:

The elements in the returned array are not sorted and are not in any particular order.

Конечно, он обычно возвращает их в порядке объявления, но это недокументировано и официально не является частью JLS.

Теоретически Swagger-Core / Swagger-Maven-плагин может обеспечить алфавитный порядок, но это, вероятно, еще менее желательно, потому что в некоторых аспектах документации, порядок имеет значение (следовательно, "position" атрибуты).

Вы поднимаете интересный вопрос о необходимости - отслеживать изменения API. Я призываю вас открыть вопрос на https://github.com/swagger-api/swagger-spec, чтобы мы могли посмотреть, сможем ли мы найти решение для него, либо в форме спецификации, либо в качестве поддержки инструмент для сравнения версий спецификации.