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

ありがとう。

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フィールドの有効な値ではありません。プロパティは、typestringと等しいformat。代わりに、patternを使用して、日付または日時パターンを定義する正規表現を指定できます。これにより、クライアントツールは日付または日時を自動的に解析できます。

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

1
Kriil