🎉

openapi-generator v6.5.0での出力をキャメルケースにする

2023/09/01に公開

OpenAPIとは

OpenAPIは、アップリケーション間で安全にやりとりするために仕様を定義するためのフォーマットです。
例えば、フロントエンド(以下FE)では配列が渡されると思っているが、バックエンド(以下BE)ではハッシュを渡すと思っていたら、不具合が起きてしまいますよね。それを揃えるための事前に「どのような情報をどのような型で通信するか」を事前に決めておくために使います。
私が思っていることよりもより複雑な使い方や正しい使い方ががあると思うので、公式ドキュメントも参照してください。
https://swagger.io/specification/
公式では

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

OpenAPI仕様(OAS)は、HTTP APIに対する標準的で言語にとらわれないインタフェースを定義しており、人間とコンピュータの両方がソースコードやドキュメントにアクセスすることなく、またネットワークトラフィックを検査することなく、サービスの機能を発見し理解することができます。適切に定義されていれば、コンシューマは最小限の実装ロジックでリモートサービスを理解し、対話することができます。
OpenAPI定義は、APIを表示するためのドキュメント生成ツール、様々なプログラミング言語でサーバーやクライアントを生成するためのコード生成ツール、テストツール、その他多くのユースケースで使用することができます。

と紹介されています。
OpenAPIドキュメントは、JSON形式またはYAML形式のいずれかで記述されます。
そのため、特定の言語に依存しないことが特徴として挙げられます。
OpenAPIとSwaggerがセットで出てくることが多く、少し調べてみると、OpenAPIはもともとSwaggerという名前だったのですが、OpenAPIに名前を変更しました。
その名残で、OpenAPI関連のツールの1つにSwaggerという名前が使われているようです。
今回題材にしているopenapi-generatorもOpenAPI関連のツールの1つです。

openapi-generatorとは

openapi-generatorとは、OpenAPIを基にAPIクライアントを自動生成してくれるツールです。
メリットは、自動生成による効率化とタイポなどの人的ミスの削減が挙げられます。
https://openapi-generator.tech/
導入方法は、openapi-generatorのgithubを見るのがいいかと思います。
https://github.com/OpenAPITools/openapi-generator

openapi-generator v6.5.0に上げる

やり方

弊社ではdockerを使ってopenapi-generatorを実行しています。
そのため

docker run --rm \
  -v ${PWD}:/local openapitools/openapi-generator-cli:v6.5.0 generate \
  -i /local/petstore.yaml \
  -g typescript \
  -o /local/out/ts \
  --additional-properties=modelPropertyNaming=camelCase

として、バージョンを指定するだけで終わりです。

問題

ここで問題が発生します。
キャメルケースで出力されたデータモデルがスネークケースで出力されてしまっています。
原因は、

docker run --rm \
  -v ${PWD}:/local openapitools/openapi-generator-cli:v5.2.1 generate \
  -i /local/petstore.yaml \
  -g typescript-axios \
  -o /local/out/ts \
  --additional-properties=modelPropertyNaming=camelCase

--additional-properties=modelPropertyNaming=camelCaseというキャメルケースで出力するためのオプションが効かなくなってしまいました。
この問題はopenapi-generatorのgithubでissueが上がっていますが、2023年8月現在で未だに解決に至っていません。
https://github.com/OpenAPITools/openapi-generator/issues/10643

解決法

先ほどのissueの中に代替案が提示されていました。
https://github.com/OpenAPITools/openapi-generator/issues/10643#issuecomment-1210068850

該当箇所のみ翻訳すると

  1. yarnを使ってopenapi-generator-cliのテンプレートをデフォルトでエクスポートします。以下のコマンドを使用してください。(CLIの呼び出し方法は分かりませんが、openapi-generator-cliにはauthorオプションがあるので、それを使用してください。参照:https://openapi-generator.tech/docs/usage#author
yarn openapi-generator-cli author template -g typescript-axios -o templates
  1. ステップ1の-oオプションで指定したtemplatesディレクトリ内でテンプレートを取得できます。
  2. templatesディレクトリの中にmodelGeneric.mustacheというファイルを見つけることができます。
  3. {{baseName}}をlambda.camelcase関数で囲みます。以下のようになります。
{{#lambda.camelcase}}{{baseName}}{{/lambda.camelcase}}

参照:https://openapi-generator.tech/docs/templating/#mustache-lambdas
5.templateDirオプションを使ってgenerateコマンドを呼び出します。
参照:https://openapi-generator.tech/docs/usage#generate

手順5を考慮するとdockerコマンドは以下のようになります。

docker run --rm \
  -v ${PWD}:/local openapitools/openapi-generator-cli:v6.5.0 generate \
  -i /local/petstore.yaml \
  -g typescript-axios \
  -o /local/out/ts \
  --template-dir /local/templates

これによって、openapi-generator v6.5.0でもキャメルケースで出力されるようになりました!
(手順1で生成されるtemplateフォルダの中身ですが、さらっと確認しても私にはよくわかりませんでした。。。)

まとめ

今回はopenapi-generatorの不具合の対処法についてまとめました。
私も先輩から言われなければ、この手段に気づけないかったので、誰かのお役に立てれば幸いです!

参考

OpenAPIとは
https://www.aeyescan.jp/media/openapi
CLI Installation
https://openapi-generator.tech/docs/installation

COUNTERWORKS テックブログ

Discussion