OpenAPISchemaから生成した型で型安全にfetchを行う (openapi typescript)

OpenAPISchemaとは？

APIの構造を記述するための標準的な仕様。Swaggerと混同してしまうが、現在はOpenAPIと呼ばれる。
SwaggerはOpenAPIを使うツール群の総称。(Swagger UIなど)

メリット

• ドキュメントとして機能する。
  Swagger UIを使って各エンドポイント,メソッドを見ることができる。
  実際にリクエストを飛ばすこともできる。(postmanなどを使う必要がなく、結構便利)

  

• Schemaからクライアントコードやサーバコードを作成できる
  本記事扱う内容(クライアントコードのみ)。
  ライブラリを使ってOpenAPISchemaから型を生成できる。
  型にはリクエストに必要なパラメータやレスポンスの型が含まれているため、
  apiリクエストやレスポンスを型安全に使用できるようになり安全性、作業効率が向上する。
  ライブラリが多数存在しており、ニーズが高いことが伺える。

ライブラリ選定

OpenAPISchemaからクライアントコードを生成するためのライブラリを選定する。
先述の通り、ライブラリが多数存在している。
こちらの記事でまとめてくれているので参考にした。

OpenAPI Generator Cli

どうやら歴史が長いライブラリの様。typescript用というわけではなく、様々な言語に対応している。
環境構築の方法がnpm,homebrew,dockerを使う方法がある。
わざわざglobalにインストールする必要性を感じないが、そこはやはり様々な言語に対応しているので全ての言語で同じライブラリを使いたい場合にそういう選択をとることになるのだろうか。

使用感としてはあまり良くなかった。
以下のような感じで使用するが、Factoryにアクセスする必要があったりメソッド名が決まっていたりするのが気になった。
多数のファイルが生成されるのでそれぞれ何をやっているかがわかりづらい。完全にライブラリ依存になってしまうのが辛い。
あとドキュメントがわかりづらい。

const res = await DefaultApiFactory().notesGet();

openapi typescript

こちらが本命。先述の記事のTOPにもあるとおり、npm trendsで見ても非常に人気がある。
私も実務でこちらのライブラリを使用している。生成された型そのままだと使いづらいので、helper typeを作成することで非常に便利に使うことができる。(参考記事)
参考記事では axios で使っているが実務ではNext.js(app router)を使っているため、fetchを使うように多少アレンジして使っている。

ライブラリの機能は型を生成するだけなのでそれ以外は開発者が実装する必要がある。
手間が増えるが依存するものは少ないので、fetchの方法を変えるなど柔軟に対応できる。

注意

メジャーバージョンアップ(6 => 7)により、生成される型が変わった。
参考記事で紹介しているのは6で生成される型に対するhelper typeの記事。
2024/09/04時点での最新バージョン 7.4.0 では同じようには使えない。

その代わりに openapi-fetch というライブラリが提供されて helperを作成することなく簡単に使用することができるようになった。ただし、fetch周りがラップされてしまうのでそこはデメリットかもしれない。

openapi-fetchを使ってみたが、補完もちゃんと効くしいい感じ。