APIの一般的なユースケースとして、定義済みの値を持つ可能性のある呼び出しのパラメータセットがある場合があります。例えばページネーションでは、クエリ結果の特定のページを要求することができます。プロデューサーとしては、コンシューマーがページあたりのエントリ数を設定できるようにする一方で、コンシューマーが各リクエストで送信することなく、定義済みの数のエントリを取得できるようにしたいと考えるでしょう。
デフォルト値の使用
ここで登場するのが「デフォルト値」です。Swaggerの仕様では、`default`を使用することで、パラメータ、モデル（およびそのプロパティ）、または応答ヘッダー（コンテナ）に値を設定できます。クライアントまたはサーバーによってこれらが省略された場合、受信側は`default`値を仮定する必要があります。
Swagger仕様における`default`キーワードの値は、やや独特です。`Any`と定義されていますが、その意図は、包含するオブジェクトの型を「コピー」することです。したがって、型が`string`のパラメータがある場合、`default`の値も`string`であることが期待されます。当然ながら、型が一致しない場合は、プロパティのデフォルト値が許可されている型とは異なる型であると宣言することになるため、意味がありません。複合型のボディパラメータの場合、`default`は複雑なデフォルト値を表すことができます。配列型のコンテナも、デフォルト値に配列構造を持つべきです。
仕様の以下の箇所で`default`プロパティを見つけることができます。
デフォルト値を使用する理由
値を定義することにはいくつかの利点があります。
- 前述の通り、リクエストからのパラメータ/プロパティ/ヘッダーの省略を可能にし、プロセスを簡素化し、必要な帯域幅を最小限に抑えます。
- APIの動作を文書化するのに役立ちます。デフォルト値を指定することで、利用者は応答で何を期待すべきかを知ることができます。
- コンテナが指定されていない場合にテスターが期待される結果を知っているため、APIテストが向上します。
デフォルト値を使用する際のよくある間違い
`default`値を使用する場合、2つの不一致が発生する可能性があります。
- コンテナにデフォルト値を定義し、そのコンテナを必須としてマークすることは、矛盾していると言えます。コンテナが必須である場合、それは常に送信され、デフォルト値が有効になることはありません。
- 2つ目のケースは、`default`をそのコンテナのサンプル値を記述する方法として使用することです。これはフィールドの適切な使用法ではなく、一部のSwaggerツールで予期せぬ動作を引き起こす可能性があります。一部のコンテナは、サンプル値を設定する別の方法を提供しています。
プロのヒント
私たちは`default`キーワードのもう一つのかなり異なる使い方をしています。それは、APIの汎用的な応答を記述するために、responsesセクションの下で使用することができます。通常、成功した応答を記述しますが、HTTPステータスコードが何であれ、エラーを公開する一般的な方法がある場合があります。その場合、`default`応答を使用して、それが使用する共通の構造を提供することができます。
詳細については、仕様のセクションをご確認ください - https://swagger.dokyumento.jp/specification/#responsesDefault。