Swaggerを使う事になり OpenAPIを触ってみると 3.0.3 と 3.1.0 が存在します。どちらを使うべきが悩んだので調べて整理してみました。3.0.3 から 3.1.0 への変更点は過去のポストを参照ください。
結論
Amazon API Gateway を使い、OpenAPIで定義されたAPI仕様書のインポート機能 を利用する場合は 3.0系（ 3.0.3 ）一択です。理由は単純に執筆時点では Amazon API Gateway が 3.1系 に対応してないからです。
また、VSCodeの拡張機能の中には 3.0.3 に対応しているものの 3.1.0 には未対応のものも多いようです。（決して 3.1.0 で書けないわけではないありません）
https://github.com/42Crunch/vscode-openapi/issues/110
https://github.com/arjun-g/vs-swagger-viewer/issues/118
それ以外であれば 3.1.0 がオススメです。
何が違うのか
OpenAPI 3.0系は JSON Schemaの定義に一部従っていません。nullable が有名ですね。nullable:true って何だ？1
- OpenAPIv2.0: JSONスキーマの拡張サブセット。JSONスキーマDraft 4との互換性が約80％になる分岐があった
- OpenAPIv3.0: JSONスキーマDraft 5との互換性が90％
- OpenAPIv3.1: JSONスキーマDraft 2019-09と互換性が100%
※ 引用元：Open API Specification 3.1と気になる仕様策定#v3.0、v3.1
OpenAPI 3.1.0 では webhooksが追加され、typeで配列が使えるようになり nullを表現できるようになりました。この他にも exampleが廃止され examplesに変更となり書き方が違います。2
ちなみに Amazon API Gateway と OpenAPI 3.0系でもまた違う
結論の補足として Amazon API Gateway は JSONスキーマDraft 4を使用してモデルを定義します。OpenAPI 3.0系とも違う仕様です。この違いにより OpenAPI 3.0系のAPI定義書で nullable:true と定義しても Amazon API Gatewayへ喰わせることは出来ないようです。
さいごに
OpenAPIを利用する際にそもそも何が問題なんだろう？と疑問を持ったのが記事を書くきっかけでした。3.1.0 がオススメですがもし 3.0.3 を利用する場合には、前提として nullable を利用しないで undefined で統一する方針とした方が良いと思います。