使用 Swagger/OpenAPI 扩展 JSON 元数据

Question

I\xe2\x80\x99m 正在寻找一种方法来声明 API 中使用的 JSON 对象的扩展元数据，该 API 使用 Swagger/OpenAPI 指定（或者类似的东西，如果有其他格式支持所请求的功能）。

\n\n

这个想法是使用此元数据自动/部分生成用于编辑此数据的用户界面。

\n\n

请求的功能列表：

\n\n

\n

• 对用户可读信息的多语言支持，例如名称、描述、占位符、示例\xe2\x80\x93 API 规范本身的名称和描述可能与最终用户\n例如 CRUD 编辑器应看到的不同。

\n

• 验证元数据
  \n我知道 Swagger/OpenAPI 中有各种字段，例如最小值、最大值、模式等。 \xe2\x80\x93 但无法为验证指定特定的（多语言）错误消息（类似于 \xe2\ x80\x9cA 用户名只能由字母\n和数字\xe2\x80\x9d 以及多种语言的翻译组成。或者\n要匹配的多个模式（每个错误消息都与之相关）。

  \n\n

  另一种验证方法可能是单独的 API 调用（例如\n检查电子邮件或用户名是否可用）

\n

• 关系元数据 例如，ID 字段实际上引用另一个对象的 ID（具有其自己的元数据）。

\n

\n

Answer 1

OpenAPI（fka.Swagger）规范可以通过使用x-属性来扩展（参见规范扩展是规范）。x-标准 OpenAPI 解析器会忽略这些属性。

\n\n

您几乎可以在规范文件中的任何位置定义自己的属性，甚至在 JSON 模式定义中也是如此，但是您必须编写自己的解析器来使用它们和/或修改 Swagger UI 等工具（这相当容易做到）在这样的工具中看到它们。

\n\n

这是一个定义中存在一些 x 张力的示例：

\n\n

swagger: "2.0"\n\ninfo:\n  version: 1.0.0\n  title: X-tension example\n  description: Using x- properties to extend the OpenAPI specification\n  x-example: we can put x-tension almost anywhere in the specification\n\npaths: {}\n\ndefinitions:\n  User:\n    properties:\n      id:\n        type: string\n      name:\n        type: string\n        maxLength: 50\n        minLength: 10\n        x-validation:\n          multiLingualMessage:\n            en: Name\'s length must be between <minLength> and <maxLength>\n            fr: La longeur de Name doit \xc3\xaatre comprise entre <minLength> et <maxLength>\n      friends:\n        type: array\n        description: An array of UserId\n        items:\n          type: string\n          x-reference:\n            type: User\n

\n\n

编辑器认为此 OpenAPI 规范有效：它忽略属性x-。

\n\n

这个例子只是一个说明x-属性，并不打算解决问题中列出的所有用例。

\n