В OpenAPI 3 (.0.3) я пытаюсь задокументировать некоторые параметры, которые повторяют большую часть их общей c информации, но затем имеют определенные c описания.
Например, У меня есть схема Date, которая выглядит следующим образом:
type: string
format: date
description: >
Format: `YYYY-MM-DD` (`full-date` defined in [RFC3339]
(https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14))
Затем я хочу использовать ее в качестве схемы для параметра (например):
- name: start
description: The start date for a thing
schema:
$ref: path/to/Date.yml
Проблема заключается в , если я предоставлю описание параметру, параметр схемы не будет отображаться, поэтому вы не увидите никакой информации о формате (за исключением того, что в этом конкретном сценарии будет отображаться string <date>, так как я использую определенный формат ... но это не всегда так).
Я знаю, что могу просто скопировать-вставить описание схемы и добавить его вручную в описание параметра, но есть немало и то, и другое лишает смысла даже определять схему по отдельности.
Есть ли чистый способ документировать это так, чтобы оба этих фрагмента информации появлялись без необходимости повторения?
Если это имеет значение, я предоставляю информацию как с ReDo c, так и с Swagger-UI. Похоже, они согласуются с этим.