OpenAPI Generatorでコード生成をしてみる

1 min read読了の目安(約1700字

はじめに

今回は OpenAPI Generator を利用したコード生成のやり方を本記事にまとめました。
なお、本記事では Docker を利用します。

作業環境

  • macOS Catalina バージョン 10.15.5
  • Docker version 19.03.13

コード生成をしてみる

手順1:OpenAPI を定義した yaml ファイルを用意します。

手順2:docker-compose ファイルを作成します。内容は以下の通りです。

docker-compose.yaml
version: "3.0"
services:
# https://github.com/openapitools/openapi-generator-cli     
openapi-generator-server:
  image: openapitools/openapi-generator-cli
  volumes:
    - ./:/local
  command: generate -g aspnetcore --additional-properties=aspnetCoreVersion=3.1 -i local/openapi.yml -o local/server

上記で実行する openapitools/openapi-generator-cli イメージの generate コマンドのオプションは以下の通りです。

  • 必須
    • g: 生成コードの言語の指定。
      • 今回の例ではaspnetcoreを指定しています。
      • g オプションで指定できる言語は公式サイトを参照ください。
    • o: yaml ファイルを指定。
    • i: 出力パスを指定。
  • 任意
    • additional-properties:-g で指定した言語に応じてオプションを指定。
      • 今回の例ではaspnetCoreのバージョンを意図的に指定しています。
      • 他にもパッケージ名などを変更することができます。
      • 各言語に応じたオプションは公式サイトの言語の URL にアクセスするとみることができます。

手順3:docker-compose.yaml を配置したディレクトリに移動し、docker-compose を起動します。
コマンドは以下の通りです。

docker-compose up -d

手順4:下記のディレクトリやコードが生成されれば成功です。
生成コードのディレクトリ

注意事項

  • 生成したコードには DB アクセスなどのビジネスロジックは何も書かれていないので、自分の手で実装する必要があります。
  • スキーマ名や operationId フィールド名などは自動生成の際にクラスやメソッド名として使用されるので、一意になるように命名してください。
    • operationId フィールド名が平仮名になっていたため、コード生成した際に意味不明なメソッド名で生成されたことがあったので。。。。[1]

まとめ

無事コード生成まで完了しました。model などが自動で生成されるため、開発工数の削減にも役立つと思います。
また、コード生成の方法は他にもやり方があるので、各個人やプロジェクトに合ったやり方を採用するのが良いかと思います。

脚注
  1. 平仮名をそのままクラス名やメソッド名として生成するためのオプションコマンドも一応存在します。 ↩︎