もう僕は OpenAPI を書きたくない

Transcript

1. もう僕は OpenAPI を書きたくない Go Connect #5 2025. 02. 19
2. 2 自己紹介 Sugar Sato (@satoIsSugar) • 2023年 BuySell Technologies入社 • 基盤チーム (Portal/Account/Approval) ◦ アソシエイトマネージャー ◦ PjM ◦ プレイングマネージャー • Go / Angular / Serverless • 熱帯植物 ◦ ビカクシダ • 猫 ◦ Lambda (♀ 2才)
3. 3 プロダクト群「バイセルリユースプラットフォーム Cosmos」の開発が進行中 リユースに必要なすべての機能を提供する 「リユースプラットフォーム Cosmos」の開発が進行中です。 Cosmosを活用して、バイセルグループ全体での業務効率改善やデータドリブン経営の深化を目指しています。 リユースプラットフォーム Cosmos 自社開発のリユース特化業務基幹システムでありサービス群の集合体 買取申込 買取・査定 在庫管理 販売 多様なチャネルで収益最大化 CRM -顧客対応- 買取種別に応じた最適なシステム構築 Visit -訪問買取 - Store -店舗買取 - Promas -商材マスタ - Appraisal -専門査定 - Stock -在庫管理 - EXS -販売管理 - Core -会員管理- Portal -データ利用- Pocket -データ基盤- 買取 専門チームによる真贋・査定と連携 査定 申込 効率的な顧客対応 在庫 在庫管理の最適・効率化 販売 データ 各事業プロセスにある データを一元管理 ：基幹システム
4. OpenAPIを書くのは好きか〜？
5. 僕は正直、面倒だなって感じてます...
6. ということで REST API の開発生産性をあげられそうな話をします
7. 01　swaggo/swag とは 02　orval との連携 03　想定質問集 04　まとめ 目次 Index
8. swaggo/swag とは 01
9. 9 特徴 • 自動ドキュメント生成 ◦ README を読んでアノテーションを記述するだけ ◦ Swagger v2.0 対応 ◦ OpenAPI v3.1 対応 • 対応しているフレームワーク多数 ◦ gin / echo / chi / etc... • CLI も同梱されている ◦ swag init ◦ swag fmt Swag converts Go annotations to Swagger Documentation 2.0
10. 10 Star History
11. 11 コード
12. 12 コード
13. 13 コード
14. 14 コマンド • swag init ◦ import _ "./docs" > main.go ◦ main.go 以外で docs を読み込むなら ▪ swag init -g http/api.go ◦ 外部の依存する構造体や自作モデルを読み出すなら ▪ swag init --parseDependency --parseInternal • swag fmt ◦ SWAG コメントのフォーマット ◦ 除外設定もできる ▪ swag fmt -d ./ --exclude ./internal
15. これらを踏まえて以前にこんな記事を書いた
16. 16 以前に書いた記事
17. スキーマ定義だけではなくて API クライアントコードを自動生成できたら楽だな
18. orval との連携性 02
19. 時は流れ バイセルに転職後...
20. Swagger / OpenAPI から FE のコードを自動生成できるライブラリがあるらしい
21. 21 orval とは • OpenAPI v3 / Swagger v2 から API クライアントコード生成 ◦ yaml や json 対応 • FE ライブラリやフレームワークとの統合 ◦ React / Angular / Vue / Svelte • CLI で簡単に実行できる Generate client with appropriate type-signatures これが自分のやりたかったことだ〜！ swag と合わせて楽できそう？
22. orval を使うにあたって OpenAPI と Swagger の違いを整理する
23. 23 OpenAPI と Swagger の違い Swagger OpenAPI 型の違い `x-nullable` で `null` を許可 `nullable: true` が標準仕様として定 義 パスパラメータの定義 `{param}` の形式のみ使用可能 `style` や `explode` を使用して詳細 な設定が可能 リクエストボディの扱い `parameters` 配列の `in: body` でリク エストボディを定義 `requestBody` を用いてリクエストボ ディを明示的に定義 レスポンスの表現 `produces` でレスポンスフォーマットを 指定 `content` を使用してフォーマットの 詳細を指定可能 セキュリティスキーム `securityDefinitions` でセキュリティス キームを定義 `securitySchemes` に統一され、よ り柔軟なセキュリティ設定が可能 拡張機能の対応 拡張プロパティ (`x-*`) を利用してカス タム定義を追加可能 `oneOf` / `anyOf` などの新機能を利 用可能
24. 24 OpenAPI と Swagger の違い 柔軟な設計をするために OpenAPI 使った方が良さそうかな 機能 Swagger OpenAPI content によるリクエストボディの柔軟な定義 ❌ ✅ oneOf / anyOf のサポート ❌ ✅ cookie パラメータ ❌ ✅ servers によるエンドポイント管理 ❌ ✅ links によるレスポンスの関係性定義 ❌ ✅
25. なるほど🧐 swaggo/swag で OpenAPI が出力できるんだよ ね？
26. 26 2023年4月6日 4月18日 5月4日 12月1日 未来 swaggo/swag/v2 リリースバージョン v2.0.0-beta v2.0.0 リリーススケジュール v2.0.0-rc1 v2.0.0-rc2 v2.0.0-rc3 v2.0.0-rc4
27. 27 2023年4月6日 4月18日 5月4日 ２０２４年12月1日 未来 swaggo/swag/v2 リリースバージョン v2.0.0-beta v2.0.0 リリーススケジュール v2.0.0-rc1 v2.0.0-rc2 v2.0.0-rc3 v2.0.0-rc4 oneOf 対応 本格的に使えそうな兆し！ 爆誕！ ※ユニオン型など未対応
28. 本格的に v2 が使えそうな 兆しがみえてきたけど課題もちらほら...
29. 29 残っている課題 • echo-swagger / gin-swagger 未対応 ◦ https://github.com/swaggo/gin-swagger/issues/315 ◦ https://github.com/swaggo/echo-swagger/pull/125 ◦ 上記のようなissue や PRが上がってきている フレームワークが swaggo/swag/v2 に対応していない ... 開発自体は行われているが 全体的にリリースがおそい...
30. 30 2023年4月6日 4月18日 5月4日 ２０２４年12月1日 未来 swaggo/swag/v2 リリースバージョン v2.0.0-beta v2.0.0 リリーススケジュール v2.0.0-rc1 v2.0.0-rc2 v2.0.0-rc3 v2.0.0-rc4 oneOf 対応 本格的に使えそうな兆し！ 爆誕！ ※ユニオン型など未対応
31. 現状使うとしたら Swagger として出力した方が良さそうかも
32. 想定質問集 03
33. 33 想定質問集 • Go からリプレイスしたらどうするの？ • コメントで記述しているとミスらない？ • OpenAPI から Go のコードを生成するものもあるんじゃないか？ 多分こんなこと思ったんじゃないでしょうか？
34. 34 • その時はその時として割り切っている ◦ リプレイス前に OpenAPI ファイルを生成 ▪ 別言語でも同じことができる物を探す ▪ もしくは真似てつくる... ◦ 愚直に OpenAPI を書くようにする ▪ スキーマの分割に勤しむ 想定質問集 Go からリプレイスし たらどうする？
35. 35 • 言いたいことめっちゃよくわかる〜 ◦ デメリット ▪ 記述ミス、ファイルの確認が必要 ◦ メリット ▪ コードで完結すること ▪ swagger ui にアクセスしながら確認できる ▪ コードベースで記述できるので逆に間違えにくい？ • e.g. API レスポンスに使う json タグ 想定質問集 コメントで記述して いるとミスらない？
36. 36 • あります！ ◦ ogen や oapi-codegen がある ▪ バイセルとして oapi-codegen 使っているプロダクト もあります ◦ おーたかさんの記事を参考にしてください ◦ https://zenn.dev/otakakot/articles/43653194 611d42 想定質問集 OpenAPI から Go のコードを生成する ものもあるんじゃな いか？
37. まとめ 04
38. 38 まとめ OpenAPI を吐き出すために使うのは道半ば • 各種フレームワークが swaggo/swag/v2 に未対応 ◦ 今後にめっちゃ期待！ • とはいえ swaggo/swag 自体は便利だし良い！ ◦ orval との連携で拡張性をもたせるために OpenAPI を検討しているだけ ◦ 一旦は Swagger で吐き出し → orval で API クライアントコード出力 アノテーションを活かして記述できるのが個人的に楽 • とはいえ課題感アリ ◦ swaggo/swag のアノテーションについて詳しくなる必要がある ◦ 意図した記述になっているか逐一 generate して確認する必要がある ▪ レビュアーの負担にならないように注意する必要
39. swaggo/swag 伸び代ですねぇ
40. Thank You
41. 41 引用 • https://github.com/swaggo/echo-swagger/pull/125 • https://github.com/swaggo/swag/tree/v2 • https://github.com/swaggo/gin-swagger/issues/315 • https://Swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/ • https://github.com/orval-labs/orval • https://orval.dev/overview • https://zenn.dev/otakakot/articles/43653194611d42 • https://qiita.com/sgash708/items/6c61faea73acc3dea8b4