web-dev-qa-db-ja.com

OpenAPI / Swaggerファイルで日付を宣言する正しい方法は何ですか？

Swagger-fileオブジェクトで日付を宣言する正しい方法は何ですか？私はそれだと思います：

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

しかし、次のような宣言がたくさんあります。

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

ありがとう。

swaggeropenapi
16
Patrick Savalle

OpenAPI Specification は、使用する必要があることを示しています。

type: string
format: date  # or date-time

使用するパターンは RFC 3339、セクション5.6 で定義されています。
したがって、dateの値は「2018-03-20」のようになり、date-timeの場合は「2018-03-20T09：12：28Z」のようになります。

patternの定義で暗黙的に定義されているため、人々がformatを明示的に指定する理由はわかりません。

24
Pascal

patternは正規表現でなければなりません。これは OpenAPI仕様 に記載されています。

pattern（この文字列は、ECMA 262正規表現方言によると、有効な正規表現である必要があります）

これは、OpenAPIオブジェクトがJSONスキーマ仕様に基づいているためです。

OpenAPI 2.0：このオブジェクトは、JSON Schema Specification Draft 4に基づいており、定義済みのサブセットを使用します。

OpenAPI 3.0：このオブジェクトは、JSON Schema Specification Wright Draft 00の拡張サブセットです。

Webサービスが RFC3339 で説明されているインターネット日付/時刻形式に準拠しない日付または日付時刻を公開する場合、dateおよびdate-timeは、formatフィールドの有効な値ではありません。プロパティは、typeがstringと等しいformat。代わりに、patternを使用して、日付または日時パターンを定義する正規表現を指定できます。これにより、クライアントツールは日付または日時を自動的に解析できます。

また、人間の消費者がより簡単に読むことができるように、説明フィールドにフォーマットを置くことをお勧めします。

1
Kriil