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から入手できます。