OpenAPI3(swagger)でのnullableとnullに関しての記法あれこれ

ドキュメントがわかりにくいのと、null許容はあるが、純粋nullに関しては言及がないのでそこに関してのワークアラウンド。

環境

openapi: 3.0.0

記法

ドキュメント曰く

Note that there is no null type; instead, the nullable attribute is used as a modifier of the base type. - Data Types | Swagger

とあり、ざっくり和訳すると

nullタイプがないことに注意してください。代わりに、nullable属性を基本的なタイプの修飾子として使用します。

ということで

nickname:
  description: ニックネーム、null可
  type: string
  nullable: true

のように nullable:true を指定すると、nullであることを示すことができる。

「nullだけ」という表現のワークアラウンド

OpenAPI3では「ここは必ずnullである」のようなものを表現する方法はない。（typeがnullが存在しない）そのため、ドキュメントとしては下記のようにnullableにして、exampleを null と記述すると、swagger editor上ではいい感じに表現されるのでコレがベターかなという形。ここらへんは仕様が変わるかもしれないので、あくまでワークアラウンド。

nullObject:
  description: null 
  type: object # exampleに文字列をおく都合上 object or string
  nullable: true
  example: null

参考リンク

• そのフィールド、nullable にしますか、requiredにしますか - Qiita - こちらはAnyofで対応するバージョンの例示がある