Как определить свойство UUID в схеме JSON и Open API (OAS)

Question

При использовании JSON Schema и Открыть спецификацию API (OAS) для документирования REST API, как определить свойство UUID ?

Answer 1

Для UUID нет встроенного type, но в спецификации OpenAPI предлагается использовать

type: string
format: uuid

Из раздела Типы данных (выделено мной):

Примитивы имеют необязательное свойство модификатора: format. OAS использует несколько известных форматов для точного определения используемого типа данных. Однако для поддержки потребностей в документации свойство format является свойством с открытыми строковыми значениями и может иметь любое значение. Форматы, такие как "email", "uuid" и т. Д., МОГУТ использоваться, даже если они не определены в данной спецификации.

Например, Swagger Codegen отображает format: uuid на System.Guid в C # или java.util.UUID в Java. Инструменты, которые не поддерживают format: uuid, будут обрабатывать его как type: string.

Answer 2

Единственный способ, который я нашел, - это вручную указать шаблон 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}'

Но я бы определенно хотел использовать более стандартизированный подход.