openapi-generatorで生成したResponseの入れ子部分の型名がMaiaとMarisで異なる

[KentaHizume]

概要

入れ子構造のレスポンス部分について、MaiaとMarisで自動生成コードのフィールドの型名が異なってしまう。
（例）BasketResponse
(Maris)'account'?: BasketResponseAccount | null;
(Maia)'account'?: AccountResponse

2024/6/24現在、入れ子構造の入れ子部分の型名を参照しているサンプルコードはないためただちに影響はないが、
参照するようなコードが出てきた場合に、MaiaとMarisでクライアント側の実装を変える必要が発生してしまう。

直接の原因は、Maia(Springdoc-openapi)のAPI定義書とMaris(Nswag)のAPI定義書が異なるためである。
具体的には、Maris側はoneOfを使用して出力されるが、Maia側は使用していない。

Maia側とMaris側の差分を吸収する方法を調査し、反映する。

• Maia

        "properties": {
          "account": {
            "$ref": "#/components/schemas/AccountResponse"
          },

• Maris

          "account": {
            "description": "会計情報を取得または設定します。\n            ",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/AccountResponse"
              }'

詳細

oneOfは同じエンドポイントから異なるスキーマのレスポンスを返したいときに使うようなので、
1種類のスキーマ or NULL のどちらかを返すことにしているMarisの定義が不自然に見えている。
よって、NSwagの出力がoneOfにならないように制御できるほうが好ましいはず。

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog''

完了条件

• MaiaとMarisで自動生成コードの型名が同一になること

[KentaHizume]

調査方針

見えている選択肢は下記で、
仕様書の該当箇所の出力をそろえる方法か、クライアントコードの出力をそろえる方法が見つかればよい。

1. NSwag(or C#)をいじる
   oneOfを使わないようにする方法があれば、仕様書の該当箇所を一緒にできるはず。

2. Springdoc-openapi(or Java)をいじる
   oneOfを使うようにする方法があれば、仕様書の該当箇所を一緒にできるはず。

3. openapi-generator
   クライアントコードの出力方法の制御方法によっては、共通化できるはず。

4. 放置する
   MaiaとMarisのクライアントコードを一致させたい、といったことは
   通常の開発のユースケースとしては起きないはずなので、一旦放置する

調査

oneOfは同じエンドポイントから異なるスキーマのレスポンスを返したいときに使うようなので、
1種類のスキーマ or NULL のどちらかを返すことにしているMarisの定義が不自然に見えている。
よって、NSwagの出力がoneOfにならないように制御できるほうが好ましいはず。

      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog''

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

[KentaHizume]

NSwag調査

DefaultResponseReferenceTypeNullHandling というオプションがある

• https://github.com/RicoSuter/NSwag/wiki/AspNetCoreOpenApiDocumentGenerator#response-nullability

デフォルト値はNotNull（もともとNullだったが、下記のPRでNotNullに変更された）

• Change default of DefaultResponseReferenceTypeNullHandling to NotNull RicoSuter/NSwag#2215

v14でこのオプションが効かなくなってしまった

• "defaultReferenceTypeNullHandling" ignored after upgrade to v14 RicoSuter/NSwag#4647

下記を追加で動作する、と書いてあるが、追加してもうまく動作しない

 document.SchemaSettings.DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull;

下記の2種類のオプションがある

• defaultReferenceTypeNullHandling
• defaultResponseReferenceTypeNullHandling

Dressca

v14に上げる際（.NET8対応）の時点は下記

• https://github.com/AlesInfiny/maris/pull/638/files

"defaultReferenceTypeNullHandling": "Null",
"defaultResponseReferenceTypeNullHandling": "NotNull",

初期構築時は下記で変わらず

• https://github.com/AlesInfiny/maris/pull/67/files

"defaultReferenceTypeNullHandling": "Null",
"defaultResponseReferenceTypeNullHandling": "NotNull",

初期構築時から定義書上oneOfが使われている