Swaggerの（公式で想定された）defaultの使い方

この記事を書こうと思った経緯

仕事でSwaggerのコードを書くことになった。
既存コードを参考にし新しいAPI分のコードを作成しようと思ったが、色々な書き方が混在していたためどれが正しい書き方か分からなくなり、混乱した。
特に気になったのが、exampleとdefaultの使い方だった。

結論

必須パラメータにdefaultを使うことは誤り。→普通にrequiredを使うこと！で、もし必須なら（そのパラメータには何らかの値がセットされることになるので）default値は使われることはない。

sample値としてdefaultを使うことは誤り。→普通にexample か examplesを使う！

公式の仕様書

Default Parameter Values

Use the default keyword in the parameter schema to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request. The value type must be the same as the parameter’s data type. A typical example is paging parameters such as offset and limit:

また、以下のようにも記載されている。

Common Mistakes

There are two common mistakes when using the default keyword:

• Using default with required parameters or properties, for example, with path parameters. This does not make sense – if a value is required, the client must always send it, and the default value is never used.
• Using default to specify a sample value. This is not intended use of default and can lead to unexpected behavior in some Swagger tools. Use the example or examples keyword for this purpose instead. See Adding Examples.

その他、Swagger関連で参考になった記事

全体像を再確認できる。久しぶりに書くことになった際におすすめ。
https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb

フューチャーさんの分かりやすい記事。
https://future-architect.github.io/articles/20200409/

また、このような規約も公開されているんですね。（すごい😊）
https://future-architect.github.io/coding-standards/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.html#%E3%81%AF%E3%81%97%E3%82%99%E3%82%81%E3%81%AB

あとがき（独り言）

以下、（愚痴に近いですが笑）swaggerをあまり触ったことがない私バックエンドエンジニアが本気でSwaggerを書くことになり、既存コードに修正を加える際に思ったことです。

まず、社内でルールをもっと厳格に決めた方がいい。

正しい英語にする。pagenationという単語がありました、おかしいですよね😅（paginationかなと）
かといってすでにいろんなところで使われているオブジェクトですから、そう簡単に変えるわけにもいかないからそのまま使うことになって
　→　大体そのままになる。エディターでスペルミスのエラーが出まくる。。

で、この記事で書いたdefaultの誤用ですね。え、なんでレスポンスのexamepleのノリでdefault使ってるの？🤔とか。

（エンジニアは往々にして無意識のうちに過去の書き方を踏襲して、統一感を重視する傾向があると思いますが、その結果間違った書き方が増えていくわけです。）
統一されていないのもアレですが🧐

これらを反面教師にして、新しいプロジェクトのコードはなるべく気をつけるようにしています。
最近はAIによるレビューもできるし、やりようはいくらでもあるかと。
スペルはやっぱり大事。英語で書くんだから、、
ただ和製英語がダメと言っている訳ではなく、それはそれでわかりやすいからOK。せめて英単語として存在しているものはそれを使おう、と。

あと勝手に小文字で繋げるのやめて〜（独り言）
pagenation・pagination、updator・updater、reponsetime・responseTime　ここら辺はあるあるですかね。