OpenAPI何もわからんですが、
Go で OpenAPI 3.0 に対応したいと思ったのですが、swaggerはどうやら OpenAPI 2.0 とやららしいので、
oapi-codegen を利用してみました。
インストール
goがインストールされれている環境で
go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
を実行すると oapi-codegen がインストールされます。
利用方法
今回は chi-server を利用しようと思います。
標準では echo サーバを生成したような記憶があります(ど忘れ)
また、READMEに書いてあるサンプルの静止コマンドでは、goのファイルが1つになってしまいますので、
運用も考え、server, types, spec の3ファイルに分かれるようにコマンドを実行します。
コマンドの引数がREADMEなどを読む感じでうまく適用できなかったのですが試行錯誤(やコードを読んで)以下で実行しています
oapi-codegen -package hoge -old-config-style -generate "chi-server" api.yaml > api.gen.go oapi-codegen -package hoge -old-config-style -generate "types" api.yaml > types.gen.go oapi-codegen -package hoge -old-config-style -generate "spec" api.yaml > spec.gen.go
このように実行することで、httpサーバとしての api.gen.go
, リクエスト/レスポンスパラメータの型としての types.gen.go
, oapiのspecファイルとしての spec.gen.go
の3ファイルがそれぞれ生成されます。
httpサーバとしての組み込み
サーバとしての組み込みは難しいことはなく、 api.gen.go
ファイルの中に Handler を生成する関数が複数用意されているので、
必要な項目て利用できるものを使いhttpサーバを起動しましょう。(詳細略:手抜き)
困ったこと
chi 以外の実装を試していないので、ほかがどうかはわかっていないのですが、chi 関しては、
swaggerを利用したバリデーションなどが標準的に生成されたコードの中で組み込まれず、自分でmiddlewareなどを実装する必要がありました。
これはもう少しよしなにやってくれるような期待をしていたのでびっくりしたのと、
security BearerAuth あたりも割と自分で実装する必要がありました。
最後に
openapi3.0 を使って実装するのが初だったので最初のYAMLの作成に結構手間取りましたが、
実際に開発の流れになると、yamlで変更したものがgoの実装に反映されたり、
webビューからリクエストを投げて動作確認をしたりということが気軽に行えるのでとても良かった。
YAMLを書く → 生成してみる → 生成された構造体/コードを見る(gitのdiff)
というのを繰り返すことで、YAMLで表現したことがどういう意味を持っているのかということが理解しやすい、
しかも生成が速いということで非常に良い感じでした。
ではでは。