OpenAPIファイルの日付
1. 序章
このチュートリアルでは、OpenAPIファイル(この場合は Swagger で実装)で日付を宣言する方法を説明します。 これにより、外部APIを呼び出すときに、標準化された方法で入力日と出力日を管理できるようになります。
2. Swagger vs. OAS
Swaggerは、 OpenAPI仕様(OAS)を実装するツールのセットであり、RESTfulAPIを文書化するための言語に依存しないインターフェースです。 これにより、ソースコードにアクセスしなくても、あらゆるサービスの機能を理解できます。
これを実装するために、プロジェクトにファイル(通常はYAMLまたはJSON 、)を作成し、OASを使用してAPIを記述します。 次に、Swaggerツールを使用して次のことを行います。
- ブラウザで仕様を編集する(Swagger Editor)
- APIクライアントライブラリの自動生成(Swagger Codegen)
- 自動生成されたドキュメントを表示する(Swagger UI)
OpenAPIファイルの例にはさまざまなセクションが含まれていますが、ここではモデル定義に焦点を当てます。
3. 日付の定義
OASを使用してUserエンティティを定義しましょう。
components:
User:
type: "object"
properties:
id:
type: integer
format: int64
createdAt:
type: string
format: date
description: Creation date
example: "2021-01-30"
username:
type: string
日付を定義するには、次のオブジェクトを使用します。
- typeフィールドはstringと同じです
- 日付の形成方法を指定するformatフィールド
この場合、日付形式を使用して、createdAt日付を記述しました。 この形式は、ISO8601完全日付形式を使用して日付を記述します。
4. 日時の定義
さらに、時刻も指定する場合は、date-timeを形式として使用します。例を見てみましょう。
createdAt:
type: string
format: date-time
description: Creation date and time
example: "2021-01-30T08:30:00Z"
この場合、ISO8601フルタイム形式を使用して日時を記述しています。
5. パターンフィールド
OASを使用すると、他の形式で日付を記述することもできます。 これを行うには、patternフィールドを使用します。
customDate:
type: string
pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
description: Custom date
example: "20210130"
明らかに、これは読みにくい方法ですが、最も強力です。 実際、このフィールドでは任意の正規表現を使用できます。
6. 結論
この記事では、OpenAPIを使用して日付を宣言する方法を見てきました。 OpenAPIが提供する標準形式と、ニーズに合わせたカスタムパターンを使用できます。 いつものように、使用した例のソースコードは、GitHubでから入手できます。