OpenAPI3.0のまともなGoコード生成ツールがいない
OpenAPI3.0のまともなGoコード生成ツールがいない
5Gを調べててOpenAPI3.0を使いたくなることがありました。 OAIとコミュニティがゴタゴタしたりSwaggerも影響を受けたりしてた印象のままで、アップデートしていませんでした。 改めてツールや動向を調べました。これはそのメモです。
はじめに
少なくともGoのコード生成でまともなツールは見つかりません。悲しいです。 ボヤいたら@t2yさんからレスもらいました。
go の openapi 化はまったくお奨めしませんが、コードジェネレーターは openapi-generator 一択じゃないですかね?https://t.co/pHsOR19Qs8
— Tetsuya Morimoto (@t2y) December 23, 2021
安定したOSSのコード生成ツールが出てくるほどにエコシステムが育っていません。
まずOAIとコミュニティのゴタゴタがあり魅力が落ちていたこと。またgRPC、GraphQLと魅力的な競合技術があるため、Webやスマホアプリ界隈がOpenAPIから離れつつあること。そして5GCでAPI定義に採用されているものの、サービス実装者(モバイル機器ベンダー)にとってOSSで公開するメリットがないこと。
この3つが原因として大きいのかなと想像しました。
モバイルベンダは5GCのサービス機器を開発するためコードジェネレータなりを自作してると想像してます。 ですが彼らにコードジェネレータを公開するモチベーションはなさそうです。ドキュメント・クライアント・レスポンスバリデーターが外部から使えれば十分だから。
じぶんは今すぐ安定したコードジェネレータが欲しいわけではないのですが。 今後は時間をかけて oapi-codegen, openapi-codegen でコード生成を改善するか自作するか関わらない道を探すか考えます。 openapi-codegenは根本対応の他にテンプレート改善で済ませる道もあるようです。
なるほど。それが要件なら仕方ないですね。oapi-codegen を触ったことがないので比較はできませんが、openapi-generator はテンプレート機能があるのでちょっとした生成コードのカスタマイズはできます。根本的にダメならコントリビュートするしかないですけどね。https://t.co/s5bqjkmn0P
— Tetsuya Morimoto (@t2y) December 23, 2021
リンク集
OpenAPIはOpenAPI Initiativeで策定されています。 いまの最新は 3.0.3 でした。
ツール
公式ドキュメントにツール一覧がある。課金勢に向けたエンプラツールとOSSのツールが用意されている。 サードパーティも含めて無課金勢で使えるツール一覧はこちら。
- Swagger Tools
- Swagger Editor
- Swagger UI
- Swagger Codegen: コードジェネレート
- OpenAPI Tools
- OpenAPI Generator: コードジェネレート(github)
- Java 8, Mavenを要求する
- docs/generators: 言語ごとのジェネレータの設定
- go-server, go-gin-server共にサーバー実装とサービス実装が分離できなくて辛い
- BUG報告はたくさんだけど長期で未解決
- OpenAPI Generator: コードジェネレート(github)
- OpenAPI.Tools: ツールのリンク集
- stoplight: エディター
- getkin/kin-openapi: パーサー, バリデーター
- deepmap/oapi-codegen: コードジェネレート
- go-swagger: GoでSwagger使うパッケージ(OpenAPI 2.0まで)
- swaggo/swag: GoコードのアノテーションからOpenAPI 2.0のドキュメント生成
- podhmo/reflect-openapi: 既存WebAPIからOpenAPI docを生成する
参考資料
- Swagger ではない OpenAPI Specification 3.0 による API サーバー開発
- Swagger ではない OpenAPI Specification 3.0 による API サーバー開発
- OpenAPI3を使ってみよう!Go言語でクライアントとスタブの自動生成まで!
- Go の Open API 3.0 のジェネレータ oapi-codegen を試してみた
- WAFとして go-swagger を選択してみた
- 本当に使ってよかったOpenAPI (Swagger) ツール
- go-swaggerを用いたWebアプリケーション開発Tips19選
やってみた
oapi-codegenでサービス定義からGoのコード生成をしようとした。パースエラーが起きた。openapi-codegenで3GPPのサービス定義からGoのコード生成した。生成されたコードがシンタックスエラーが大量発生。 これからやること。
- パース失敗の原因を調べる
- 3GPPの定義を確認
- oapi-codegenの修正
- openapi-codegenの生成コードの修正