emahiro/b.log

日々の勉強の記録とか育児の記録とか。

トップ > Go > ogen が v1 になっていたので変わったところも含めて試してみた

ogen が v1 になっていたので変わったところも含めて試してみた

Go OpenAPI

サマリ

現職で OpenAPI からのコード生成ツールとして ogen を採用して使っているのですが、この ogen がしばらく見ないうちに v1 (現時点の最新は v1.2.1) に進んでいたので、v1 以前との違い等々を調べてみました。

github.com

v1 以前と変わったところ

設定ファイルができた

ogen を実行するディレクトリと同階層に ogen.yml という設定ファイルが必要になりました。
この設定ファイルでは後述する生成するファイル（server や client) の対象を選択する設定や、コード生成時に発生するエラーを ignore したりすることができます。

オプションが変わった

まず最初に気づいたのはここでした。v1 以前とオプションが変わっています。

特に現職ではコード（特に API のリクエストやレスポンスの部分の）生成に ogen を利用しており、server や client といったコードの生成は利用していなかったのでのでちょっと困りました。

例. 元々使っていたオプションからなくなったのは以下

  • -no-client : Client のコードを生成しないオプション
  • -no-server : Server のコードを生成しないオプション

その他 -allow-remote や -debug.noerr といったオプションもなくなっていました。

現在利用できるオプションは以下です。

flag provided but not defined: -no-client
Usage: ogen [options] <spec>
  -clean
        Clean generated files before generation
  -color
        Enable color logging (default true)
  -config string
        Path to config file
  -cpuprofile string
        Write cpu profile to file
  -loglevel value
        Zap logging level
  -memprofile string
        Write memory profile to this file
  -memprofilerate int
        If > 0, sets runtime.MemProfileRate (default -1)
  -package string
        Target package name (default "api")
  -target string
        Path to target dir (default "api")
  -v    Enable verbose logging
  -version
        Print version and exit

では従来のような Client や Server のコード生成をしない（抑制する）ための方法はどうするのか？というと、config ファイルに生成するファイルを enable する設定をかくという方式でした。
ちなみに再掲ですが、現職では Clinet や Server といった生成対象のコードをプロダクションでは利用しておらず、もっぱら Req/Resp のインターフェースの管理としての自動生成のみを使っていたので、新規で生成されるファイルは必要ありませんでしたので、最初オプションがなくなったときは困りました。

v1 以降は以下のような設定ファイルを書けばまずはデフォルトの生成対象を残した状態で、余計なコード生成はスキップさせることができます。

generator:
  features:
    disable_all: true

oneOf が正式にサポートされた

もともと oneOf はサポートされていましたが、プリミティブな型のみだったりしてたのがどうやら正式にサポートされたようです。

Sum type | ogen

ogen 拡張ができた。

Extentions というところを見るとわかりますが、OpenAPI ドキュメントを記載するときに、ogen のオプションを付けることができます。

個人的に便利だなと思ったのは以下です。

  • Custom Type Name をつけることができること。

    • ogen が生成するコードの schema を使うときに、適切にコンポーネントが切られていないと ogen 側での独自の命名規則（OperationId 等々を使っている）に沿って Struct が生成されてしまうのが少し気持ちわるかったのですが、このオプションを使うと名前を割り当てることができます。

  • Struct Field Tags で生成する schema に任意の tag を割り当てることができる。

    • 特に Go だと ORM を使うときにマッピングのための tag を打つケースが多いですが、OpenAPI の定義側に tag を指定することで、tag ごとコードを生成することができます。
    • ORM とかの定義を１から作らずともよいのでこれも良い機能だなと思いました。ORM のための Entity を Response でそのまま使うのか？という点は若干議論が分かれそうですが。

まとめ

OpenAPI を使うって言うとちょっともの好き感ありますが、実際枯れている仕様でもあるので選択肢に上がることも多いかと思います。
OpenAPI を使って自動生成を考えるときに、適切なライブラリ選定が難しい問題がありますが、その中でも ogen は注目していた一つで実際に商用環境でも使っていて十分使えそうだなと思っていたところで、 v1 になり色々便利な機能も増えていたので今回はその学習のためにブログを残しました。

また使っていく中で気づいたことがあったらまとめようと思います。