如何在 OpenAPI 中注释字符串属性以允许多行文本

Question

上下文：我们希望通过实体的 OpenAPI 建模尽可能地控制我们的 UI。

问题：使用 OpenAPI 3.1.0，是否有一种既定的方法来声明字符串属性旨在包含较长的多行文本，而不仅仅是短文本？

例如我们希望将这样的注释放置到像

curriculumVitae

这样的属性，而不是

surname

，以便 UI 知道使用更大的文本字段，也许还有不同的布局。

我想到的想法：

• 使用类似

  contentMediaType: text/plain

  的东西。这并不完全意味着有关文本长度的任何信息，但通常不会用于“短”属性，例如

  surname

  。因此，可以在我们的上下文中仔细阅读它。
• 引入

  x-columns

  和

  x-rows

  等扩展属性。这在 OpenAPI 文档中感觉不合适。
• 创建一个允许换行的正则表达式，并将其用作属性的

  pattern

  。仅当所有单行字符串属性都带有排除换行符的

  pattern

  时，这才真正起到区分作用。所以，这不太实用。
• 定义我自己的格式，例如

  format: multi-line

  。这可以在一个系统内工作，但对该系统之外的任何工具都毫无用处。至少它在某种程度上与正确 UI 表示的其他提示一致，例如

  format: date-time

  或

  format: password

  。

Answer 1

使用 OpenAPI 3.1.0，是否有一种既定的方法来声明字符串属性旨在包含较长的多行文本，而不仅仅是短文本？

不，JSON Schema（因此 OpenAPI）没有任何多行字符串的概念/符号。