web-dev-qa-db-ja.com

JSONスキーマおよびOpen API（OAS）でUUIDプロパティを定義する方法

JSON Schema および Open API specification（OAS） を使用してREST APIをドキュメント化する場合、どうすれば [ 〜＃〜] uuid [〜＃〜] プロパティ？

jsonschemaopenapi
9
Slava Fomin II

UUIDにはtypeが組み込まれていませんが、OpenAPI仕様では、

type: string
format: uuid

データ型 セクションから（エンファシスマイニング）：

プリミティブには、オプションの修飾子プロパティformatがあります。 OASは、いくつかの既知の形式を使用して、使用するデータタイプを詳細に定義します。ただし、ドキュメントのニーズをサポートするために、formatプロパティはオープンな文字列値のプロパティであり、任意の値を設定できます。 "email"、"uuid"などの形式は、この仕様で定義されていない場合でも使用できます。

たとえば、Swagger Codegenはformat: uuidをC＃のSystem.GuidまたはJavaのJava.util.UUIDにマップします。 format: uuidをサポートしていないツールは、type: stringとして処理します。

13
Helen

私がこれまでに見つけた唯一の方法は、再利用可能なスキーマコンポーネントとして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}'

しかし、私は間違いなく、より標準化されたアプローチを使用したいと思います。

6
Slava Fomin II