OAS3 указала версию службы - PullRequest
Новая
       14

OAS3 указала версию службы

1 голос
/ 13 марта 2019

В настоящее время мы указываем новый API службы REST, используя спецификацию службы OpenAPI v3 OAS3 . По множеству разных причин нам нужно / нужно сделать сервисный API версионным с самого начала (это обусловлено факторами, не зависящими от нас).

Схема управления версиями, которую мы хотели бы использовать: Управление версиями URL-пути - то есть что-то вроде .../v1/ourservice.

Кто-нибудь знает, как такая схема управления версиями может отслеживаться в спецификации OAS3?

До сих пор я видел только глобальный атрибут version в OAS3 - но ничего такого, что позволяло бы нам легко указывать несколько версий в одном файле YAML (или это неправильный способ сделать это в первую очередь?) .

К вашему сведению, мы планируем использовать нисходящий подход, то есть определить наш сервисный API как OAS3 YAML, а затем приступить к генерации кода на стороне сервера и / на стороне клиента с использованием генератора Swagger.

1 Ответ

2 голосов
/ 19 марта 2019

version в документе OpenAPI относится к версии документа, а не к версии API.

С Спецификация :

версия строка ТРЕБУЕТСЯ . Версия документа OpenAPI (которая отличается от версии спецификации OpenAPI или версии реализации API).

Итак, к сожалению, есть три версии, с которыми вам нужно иметь дело. Вот как они выглядят: 

oepnapi: 3.0.2
  • Версия документа. Я обычно выставляю это как хеш git SHA1 для автоматически сгенерированного документа.
    Пример (см. version): 
  title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
  • Версия API.
    Некоторые люди считают путь контроля версий спорной, но многие из нас (включая меня), должны сделать это по ряду различных причин вне нашего контроля. Общий способ достижения этого во всех версиях спецификации - определение версии пути в baseUrl. Например, ваш базовый URL может быть /nested/v1 или просто /v1. К сожалению, это будет охватывать только подход v1.

OAS3 поддерживает шаблон серверной переменной для более сложных конфигураций версий API. Это выглядит именно то, что вы ищете. Однако эти переменные еще не полностью поддерживаются во всех генераторах в OpenAPI Generator. Если вы имеете в виду определенные генераторы, откройте для них проблему , поскольку первоначальная поддержка, по-видимому, существует только в клиентских генераторах ES6 для Ruby, PHP, Python и JavaScript.

...