[解決済み] OpenAPI(Swagger)で文字列やNULLを含むプロパティを定義する方法は？

質問

JSONスキーマファイルがあり、プロパティの1つが次のように定義されています。 string または null :

"type":["string", "null"]

YAMLに変換すると（OpenAPI/Swaggerで使用するため）、こうなります。

type:
  - 'null'
  - string

と表示されますが、Swagger Editorではエラーが表示されます。

スキーマの "type"キーは文字列でなければなりません。

OpenAPIでNULL可能なプロパティを定義する正しい方法は何ですか？

どのように解決するのですか？

OpenAPIのバージョンに依存します。

OpenAPI 3.1

あなたの例は、JSON Schema 2020-12と完全に互換性のあるOpenAPI 3.1において有効です。

type:
  - 'null'   # Note the quotes around 'null'
  - string

# same as
type: ['null', string]

上記は同等です。

oneOf:
  - type: 'null'   # Note the quotes around 'null'
  - type: string

は nullable キーワードは OAS 3.0.x では存在せず、OAS 3.1 では削除され、代わりに 'null' 型の代わりに削除されました。

OpenAPI 3.0.x

Nullableな文字列は以下のように定義されています。

type: string
nullable: true

OpenAPIの3.0.xまでのバージョンでは、JSON Schemaの構文とは異なり、独自の フレーバーのJSON Schemaを使用するからです。 ("拡張サブセット")を使用するからです。違いのひとつは type は単一の型でなければならず、型のリストにはできないことです。また 'null' 型もありません。その代わりに nullable キーワードは type を許可するモディファイアです。 null の値を指定します。

OpenAPI 2.0

OAS2 は 'null' をデータ型としてサポートしていないので、運が悪いとしか言いようがありません。使用できるのは type: string . しかし、いくつかのツールは x-nullable: true をベンダーの拡張機能としてサポートしているツールもあります。

nullを適切にサポートするためにOpenAPI v.3への移行を検討してください。