使用Swagger / OpenAPI扩展JSON元数据

Question

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

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

所请求功能的列表：

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

• 验证元数据
  我知道Swagger / OpenAPI中有各种字段，如最小值，最大值，模式等等 - 但是没有办法为验证指定特定的（多语言）错误消息（类似“用户名必须包含字母”之类的内容 和数字只有“和多种语言的翻译”。要么 要匹配的多个模式（彼此错误消息绑定 它）。

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

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

Answer 1

可以使用x-属性扩展OpenAPI（fka.Swagger）规范（参见Specification Extension是规范）。标准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-属性的说明，并不打算解决问题中列出的所有用例。