OpenAPI generator

[kounoike]

@openapitools/openapi-generator-cli を使用してクライアントコードを生成しようとしています。

npx  @openapitools/openapi-generator-cli generate \
    -i http://mirakc:40772/api/docs \
    -g rust \
    -o mirakc-client \
    --skip-validate-spec \
    --package-name mirakc-client

として生成したコードをビルドしたところ、こんなエラーが出ました。

error[E0004]: non-exhaustive patterns: `RecordingStatus::String(_)` and `RecordingStatus::String(_)` not covered
  --> src/models/recording_status.rs:16:35
   |
16 | #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
   |                                   ^^^^^^^^^ patterns `RecordingStatus::String(_)` and `RecordingStatus::String(_)` not covered
   |
note: `RecordingStatus` defined here
  --> src/models/recording_status.rs:18:10
   |
18 | pub enum RecordingStatus {
   |          ^^^^^^^^^^^^^^^
19 |     String(String),
20 |     String(String),
   |     ------ not covered
21 |     String(String),
   |     ------ not covered
   = note: the matched value is of type `RecordingStatus`
   = note: this error originates in the derive macro `Serialize` (in Nightly builds, run with -Z macro-backtrace for more info)

実際、コードを見たところこんなコードが生成されていました。

/// RecordingStatus : A recording status.
/// A recording status.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum RecordingStatus {
    String(String),
    String(String),
    String(String),
    RecordingStatusOneOf(Box<models::RecordingStatusOneOf>),
}

じゃあdocsでどう定義されているかと見ると、

      "RecordingStatus": {
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "recording"
            ]
          },
          {
            "type": "string",
            "enum": [
              "finished"
            ]
          },
          {
            "type": "string",
            "enum": [
              "canceled"
            ]
          },
（以下略）

となっています。試しにファイル保存したdocsの上記3つを "enum": ["recording", "finished", "canceled"] と書き換えてgeneratorを再実行したところ、今度はちゃんとビルド出来るコードになりました。

手元で書き換えれば良いことではありますが、mirakc側での対応でそのまま生成出来るコードになったりしますか？

[masnagam]

serdeのenumの既定値の表現はExternally taggedなのですが，これをutoipaがうまく表現できていないように見えます．

表現は変わってしまいますが，RecordingStatusに#[serde(tag = "type")]を追加することで，コードを自動生成可能な表現が生成されているように見えます（この表現もあまり良いものではありませんが）．

{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "recording"
          ]
        }
      }
    },
    {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "finished"
          ]
        }
      }
    },
    {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "canceled"
          ]
        }
      }
    },
    {
      "type": "object",
      "required": [
        "reason",
        "type"
      ],
      "properties": {
        "reason": {
          "$ref": "#/components/schemas/RecordingFailedReason"
        },
        "type": {
          "type": "string",
          "enum": [
            "failed"
          ]
        }
      }
    }
  ],
  "title": "RecordingStatus",
  "description": "A recording status."
}

修正箇所は以下のみです．

--- a/mirakc-core/src/recording.rs
+++ b/mirakc-core/src/recording.rs
@@ -2528,7 +2528,7 @@ impl Record {

 /// A recording status.
 #[derive(Clone, Debug, Deserialize, Serialize)]
-#[serde(rename_all = "camelCase")]
+#[serde(rename_all = "camelCase", tag = "type")]
 #[derive(ToSchema)]
 #[schema(title = "RecordingStatus")]
 pub enum RecordingStatus {

これでよければ，上記修正をmainに適用します．

[masnagam]

生成コードを見ると，String(String)となっていることから，上記修正を適用してもObject(...)となりそうな気がしますね．．．

生成ツールにも問題があるみたいですね．
https://github.com/OpenAPITools/openapi-generator/issues?q=is%3Aissue+is%3Aopen+rust+enum

[kounoike]

なるほど・・・なかなか難しいですね
もし、その修正を既にローカルブランチで持っているのでしたらpushしてもらえるとこちらでテストできそうです。無かったら私のForkした方で試します。
こちらでクライアント生成＆テストしてみてからマージするかどうかは考えましょう

[masnagam]

型自体を変換しないと無理っぽいので，変更してみました．
https://github.com/mirakc/mirakc/tree/fix-web-openapi

多分これなら自動生成できると思います．

他にも自動生成できないモデルがあればまとめて修正してしまうので，そういうのが見つかったらコメントをください．

[kounoike]

自動生成されたコードでビルド出来ないのは上記のRecordingStatusだけだったので、変更後も自動生成出来るようであれば大丈夫だと思います。
ビルドされたコードが正しく動くかはまた別問題ですが・・・

自動生成するときに --skip-validate-spec を付けないと下記エラーが出て生成出来なかったのですが、もしこのエラーの意味が分かるようでしたら対処していただけるとちょっと嬉しいかもしれないです。
（ライセンス情報の取得周りなので、生成物のライセンス表記が変わるかも？　なので）

vscode ➜ ~/t $ pnpx  @openapitools/openapi-generator-cli generate     -i http://tuner:40772/api/docs     -g rust     -o mirakc-client      --package-name mirakc-client
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 2
Errors: 
        -attribute info.license.identifier is missing
Warnings: 
        -attribute info.license.identifier is missing

        at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:717)
        at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:744)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

[masnagam]

どうもidentifierに設定すべきものがnameに設定されているように見えますね．

    "license": {
      "name": "MIT OR Apache-2.0"
    },

確認してみます．

[masnagam]

openapiの仕様上はidentifierはoptionalですね．nameは必須みたいですが．
https://swagger.io/specification/

utoipa-genでは以下のように実装されていて，
https://github.com/juhaku/utoipa/blob/2f7acf13d2a6c9522fc0a752a7c113f0fafa56b5/utoipa-gen/src/openapi/info.rs#L251

ここでstringはCARGO_PGK_LICENSEです．Cargo.tomlの仕様上はSPDX形式ですね．
https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields

utoipa-genの実装を見た感じでは，identifierも指定できそうに見えるので，少し試してみます．

[masnagam]

utoipa-genを修正したほうが楽ですが，ひとまずmirakcを修正しておきます．

[kounoike]

ありがとうございます！
ふと、そこを直したら他のエラーが出たりしたらどうしよう、と心配してましたが、そういうこともなかったみたいですね
良かったです

[masnagam]

swagger uiがバグってて，ライセンスへのリンクがおかしくなるみたいですが，まあこれは些細な問題なのでしょう．
https://spdx.org/licenses/MIT%20OR%20Apache-2.0.html

SPDX license expressionなんだから，OR/ANDなどで複数ライセンスが指定されることがあるのですが，それを全く考慮していないですね．
仕様でurlとidentifierは排他的であると記述しているあたりから，ライセンスは１つである（もしくは１つのライセンスファイルにすべて記述されている）と誤解しているような感じです．

[masnagam]

0ac59d3 で対応しました．

ローカルでfix-web-openapiブランチからビルドしたmirakcを実行し，

docker run --rm -it --network=host openapitools/openapi-generator-cli generate -i http://localhost:40772/api/docs -g rust -o mirakc-client --package-name mirakc-client

が正常終了するまでは確認しました．生成されたコードの確認はしていません．

[kounoike]

そこまでいけば生成されたコードが普通にcargo build通るとこまで行ってるはずなので、後ほど確認してみます

[masnagam]

utoipa-genへのPRがマージされたので，utoipa-genの新しいバージョンがリリースされたら 0ac59d3 をrevertします．

[masnagam]

#2121 をmainブランチにマージしました