Как записать вычисленное значение по умолчанию в OAS3 - PullRequest
Новая
       5

Как записать вычисленное значение по умолчанию в OAS3

0 голосов
/ 09 января 2019

Я обновляю свои спецификации API (OAS 3.0.0), и у меня возникают проблемы с пониманием того, как правильно смоделировать «сложное» значение по умолчанию.

Как правило, значения по умолчанию для параметров являются скалярными значениями (т.е. поле offset имеет значение по умолчанию 0). Но в указанном API-интерфейсе значение по умолчанию фактически рассчитывается на основе других предоставленных параметров.

Например, что если мы возьмем модель Pet из примера документации и решим, что все животные должны быть помечены. Если пользователь API хочет предоставить тег, отлично. Если нет, оно будет равно названию.

Одна возможность: 

Pet:
  required:
    - id
    - name
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
    tag:
      type: string
      default: '#/components/schemas/Pet/name'

Здесь хранится значение пути по умолчанию, но я бы хотел, чтобы оно объяснило, что значение по умолчанию будет вычислено.

Бонусные баллы, если я могу кодировать информацию из родительской схемы.

Является ли альтернативой просто описать поведение в поле описания?

1 Ответ

0 голосов
/ 12 января 2019

Спецификация OpenAPI не поддерживает динамические / условные значения по умолчанию. Вы можете задокументировать поведение только в description.

Тем не менее, вы можете использовать расширения спецификации (x-...) для добавления пользовательской информации в ваши определения, например так: 

tag:
  type: string
  x-default: name

или 

tag:
  type: string
  x-default:
    propertyName: name

# or similar

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

...