Я использую Rest Doc для документирования моих API отдыха. На основе методов TestNg я генерирую фрагменты, которые позже я использую в asciidoc.
Например, у меня есть конечная точка отдыха для извлечения людей, а также метод TestNg для его документирования. Итак, я могу использовать его в моем документе ASCII, как это:
=== Get People
Get the people registered.
operation::get-people[snippets='http-request,request-fields,http-response,response-fields,error-codes']
Но теперь, мой API изменился, и я ввел управление версиями, поэтому API отличается от версии 1 до версии 2. Я также хочу документировать это правильно, но я не знаю, как это сделать, будучи «менее навязчивый "возможно.
Я бы хотел, чтобы в моей документации была эта структура
Ресурсы
v1
getPeople
v2
getPeople
Для API, который действительно изменяется от одной версии к другой, мне нужно сгенерировать отдельный фрагмент для каждой версии, поддерживаемой API, поскольку, возможно, поля запроса или поля ответа отличаются.
Но у меня также есть некоторые другие конечные точки отдыха, которые имеют один и тот же API от одной версии к другой, и я думаю, что мне также нужно генерировать фрагменты для каждой версии, поскольку версия является частью пути остальной конечной точки.
Есть ли у вас какие-либо идеи о том, как добавить версии в остальные документы?