Управление версиями в OpenAPI - PullRequest
Новая
       1

Управление версиями в OpenAPI

0 голосов
/ 14 февраля 2019

Мы собираемся внедрить сервисный API для моего клиента, который состоит из ряда сервисов, скажем, ServiceA, ServiceB и ServiceC.Каждый сервис может со временем (независимо) вводить новые версии, в то время как старые версии все еще существуют.Таким образом, мы можем иметь:

  • ServiceA v1
  • ServiceA v2
  • ServiceB v1
  • ServiceC v1
  • ServiceC v2
  • ServiceC v3

Мы должны задокументировать этот API с использованием OpenAPI.Я не слишком знаком с OpenAPI, но, насколько я понимаю, вы, как правило, используете полную версию API, а не отдельные службы.

Как обычно документировать такое управление версиями с использованием OpenAPI?Лично я вижу два варианта, но я, скорее всего, что-то упускаю:

  1. Добавить каждую версию того же сервиса в качестве отдельных сервисов в документации (но это со временем приводит к раздутому API с большим количеством сервисов).)
  2. Увеличивайте все версии сервисов и версию API в целом каждый раз, когда один сервис меняет версию, поэтому всегда есть версии 1, 2 и 3 для каждого сервиса, даже если некоторые из них идентичны (но это вводит многоиз ненужных служебных версий).

Любой вклад будет высоко ценится.

1 Ответ

0 голосов
/ 20 февраля 2019

Я ищу тот же ответ, удачи пока нет?

Я также хочу добавить поддержку версий в REST API, например / v1 / / v2 /

и т. Д.старое в том же файле.

Использование объекта Tag недостаточно, поскольку это может привести к путанице.Если теги названы как RouteV1 и RouteV2, они могут работать, но вывод все еще смешанный.Хорошей идеей также будет возможность создания клиента с использованием редактора swagger.

Было бы неплохо, если бы это было похоже на

/ v1 /

paths:

info

/ v2 /

paths: 

info

До сих пор я вижу только наихудший случай для указания каждой сервы в отдельном файле.

...