Question

使用JSON Schema和Open API specification (OAS)来记录REST API时，如何定义UUID属性？

Answer 1

UUID没有内置type，但OpenAPI规范建议使用

type: string
format: uuid

来自Data Types部分（强调我的）：

基元有一个可选的修饰符属性：format。 OAS使用几种已知格式来详细定义所使用的数据类型。但是，为了支持文档需求，format属性是一个开放的字符串值属性，可以具有任何值。 即使本规范未定义，也可以使用"email"，"uuid"等格式。

例如，Swagger Codegen将format: uuid映射到C＃中的System.Guid或Java中的java.util.UUID。不支持format: uuid的工具会将其处理为type: string。

Answer 2

自从最初提出问题以来，JSON Schema规范已扩展为提供内置支持，用于指定和验证string类型的JSON字段是否为UUID-具体来说，它遵循由定义的UUID格式RFC4122，例如“ f81d4fae-7dec-11d0-a765-00a0c91e6bf6”。

该支持是在JSON模式规范版本2019-09中添加的（以前称为draft-08）。扩展了JSON Schema Validation组件规范，以便可以为string类型的schema字段指定的现有“ format”关键字现在支持名为“ uuid”的新内置格式。

下面的示例JSON模式声明了一个（强制）字段，其名称为“ id”，类型为字符串，必须将其格式设置为UUID-

{
  "$schema": "http://json-schema.org/draft/2019-09/schema#",
  "title": "My JSON object schema",
  "description": "Schema for the JSON representation of my JSON object.",

  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for my object. (A UUID specified by RFC4122).",
      "type": "string",
      "format": "uuid"
    }
  },
  "required": ["id"]
}

请注意，在撰写本文时，“ JSON模式用户指南”（"Understanding JSON Schema"）的部分涵盖了内置字符串验证的示例-JSON模式参考>特定于类型的关键字>字符串> {{3} }-未提及UUID支持，因为它已经过时-目前仅描述JSON Schema draft-7。

对于你们当中的Java开发人员来说，JSON模式使用的RFC4122格式与Java的UUID类的字符串表示形式兼容-Format也提到了RFC 4122。

有关更多详细信息，请参见-

JSON Schema Validator规范的第7部分。“格式”> 7.3的语义内容词汇表。定义的格式> Javadoc-官方规范。

此GitHub问题7.3.5. Resource Identifiers（01/2018）要求添加支持。并且该增强功能已在03/2019中正式实施。请参阅拉取请求https://github.com/json-schema-org/json-schema-spec/issues/542。

Answer 3

我到目前为止找到的唯一方法是手动将RegEx模式指定为可重用的模式组件：

openapi: 3.0.1

paths:
  /transactions/:
    post:
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionId:
                    $ref: '#/components/schemas/uuid'

components:
  schemas:
    uuid:
      type: string
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

但是，我肯定希望使用更标准化的方法。

如何在JSON Schema和Open API（OAS）中定义UUID属性

3 个答案: