2

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

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

要求的功能列表：

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

  • 验证元数据
    我知道 Swagger/OpenAPI 中有各种字段，例如最小值、最大值、模式等——但无法为验证指定特定的（多语言）错误消息（例如“用户名必须由字母和数字组成”仅”以及多种语言的翻译）。或要匹配的多个模式（彼此关联的错误消息）。

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

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

4

1 回答 1

3

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

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

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

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-属性的说明，并不打算解决问题中列出的所有用例。

于 2016-07-02T18:40:21.480 回答