openapi-generator v6.5.0での出力をキャメルケースにする
OpenAPIとは
OpenAPIは、アップリケーション間で安全にやりとりするために仕様を定義するためのフォーマットです。
例えば、フロントエンド(以下FE)では配列が渡されると思っているが、バックエンド(以下BE)ではハッシュを渡すと思っていたら、不具合が起きてしまいますよね。それを揃えるための事前に「どのような情報をどのような型で通信するか」を事前に決めておくために使います。
私が思っていることよりもより複雑な使い方や正しい使い方ががあると思うので、公式ドキュメントも参照してください。
公式では
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クライアントを自動生成してくれるツールです。
メリットは、自動生成による効率化とタイポなどの人的ミスの削減が挙げられます。
導入方法は、openapi-generatorのgithubを見るのがいいかと思います。
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月現在で未だに解決に至っていません。
解決法
先ほどのissueの中に代替案が提示されていました。
該当箇所のみ翻訳すると
- 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の-oオプションで指定したtemplatesディレクトリ内でテンプレートを取得できます。
- templatesディレクトリの中にmodelGeneric.mustacheというファイルを見つけることができます。
- {{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とは
CLI Installationポップアップストアや催事イベント向けの商業スペースを簡単に予約できる「SHOPCOUNTER」と商業施設向けリーシングDXシステム「SHOPCOUNTER Enterprise」を運営しています。エンジニア採用強化中ですので、興味ある方はお気軽にご連絡ください! counterworks.co.jp/
Discussion