json - 使用 Swagger/OpenAPI 扩展 JSON 元数据

Question

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

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

请求的功能列表:

• 多语言支持用户可读信息，如姓名、 description, placeholder, examples – 的名称和描述 API 规范本身可能不同于最终用户的规范 例如，CRUD 编辑器应该看到。

• 验证元数据
  我知道 Swagger/OpenAPI 中有各种字段，如最小值、最大值、模式等——但是没有办法为验证指定特定的(多语言)错误消息(比如“用户名必须由字母组成 和数字”以及多种语言的翻译)。或者 要匹配的多个模式(与每个其他错误消息相关联 到它)。

  另一种验证方法可能是 API 调用(例如 检查电子邮件或用户名是否可用)

• 关系元数据 ID 字段实际上引用另一个 ID 的示例 对象(具有自己的元数据)。

Answer 1

可以使用 x- 属性扩展 OpenAPI (fka.Swagger) 规范(参见 Specification Extension 是规范)。这些 x- 属性会被标准 OpenAPI 解析器忽略。

您几乎可以在规范文件中的任何位置定义您自己的属性，即使是在 JSON 模式定义中，但您必须编写自己的解析器才能使用它们和/或修改诸如 Swagger UI 之类的工具(这很容易做到) 在此类工具中查看它们。

这是一个在定义中有一些 x-tensions 的例子:

swagger: "2.0"

info:
  version: 1.0.0
  title: X-tension example
  description: Using x- properties to extend the OpenAPI specification
  x-example: we can put x-tension almost anywhere in the specification

paths: {}

definitions:
  User:
    properties:
      id:
        type: string
      name:
        type: string
        maxLength: 50
        minLength: 10
        x-validation:
          multiLingualMessage:
            en: Name's length must be between <minLength> and <maxLength>
            fr: La longeur de Name doit être comprise entre <minLength> et <maxLength>
      friends:
        type: array
        description: An array of UserId
        items:
          type: string
          x-reference:
            type: User

此 OpenAPI 规范被编辑者认为是有效的:它忽略了 x- 属性。

此示例仅说明 x- 属性，并不打算解决问题中列出的所有用例。