Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Sugar Sato
February 19, 2025

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

Sugar Sato

February 19, 2025
Tweet

More Decks by Sugar Sato

Other Decks in Programming

Transcript

  1. 2 自己紹介 Sugar Sato (@satoIsSugar) • 2023年 BuySell Technologies入社 •

    基盤チーム (Portal/Account/Approval) ◦ アソシエイトマネージャー ◦ PjM ◦ プレイングマネージャー • Go / Angular / Serverless • 熱帯植物 ◦ ビカクシダ • 猫 ◦ Lambda (♀ 2才)
  2. 3 プロダクト群「バイセルリユースプラットフォーム Cosmos」の開発が進行中 リユースに必要なすべての機能を提供する 「リユースプラットフォーム Cosmos」の開発が進行中です。 Cosmosを活用して、バイセルグループ全体での業務効率改善やデータドリブン経営の深化を目指しています。 リユースプラットフォーム Cosmos 自社開発のリユース特化業務基幹システムでありサービス群の集合体

    買取申込 買取・査定 在庫管理 販売 多様なチャネルで収益最大化 CRM -顧客対応- 買取種別に応じた最適なシステム構築 Visit -訪問買取 - Store -店舗買取 - Promas -商材マスタ - Appraisal -専門査定 - Stock -在庫管理 - EXS -販売管理 - Core -会員管理- Portal -データ利用- Pocket -データ基盤- 買取 専門チームによる真贋・査定と連携 査定 申込 効率的な顧客対応 在庫 在庫管理の最適・効率化 販売 データ 各事業プロセスにある データを一元管理 :基幹システム
  3. 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
  4. 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
  5. 21 orval とは • OpenAPI v3 / Swagger v2 から

    API クライアントコード生成 ◦ yaml や json 対応 • FE ライブラリやフレームワークとの統合 ◦ React / Angular / Vue / Svelte • CLI で簡単に実行できる Generate client with appropriate type-signatures これが自分のやりたかったことだ〜! swag と合わせて楽できそう?
  6. 23 OpenAPI と Swagger の違い Swagger OpenAPI 型の違い `x-nullable` で

    `null` を許可 `nullable: true` が標準仕様として定 義 パスパラメータの定義 `{param}` の形式のみ使用可能 `style` や `explode` を使用して詳細 な設定が可能 リクエストボディの扱い `parameters` 配列の `in: body` でリク エストボディを定義 `requestBody` を用いてリクエストボ ディを明示的に定義 レスポンスの表現 `produces` でレスポンスフォーマットを 指定 `content` を使用してフォーマットの 詳細を指定可能 セキュリティスキーム `securityDefinitions` でセキュリティス キームを定義 `securitySchemes` に統一され、よ り柔軟なセキュリティ設定が可能 拡張機能の対応 拡張プロパティ (`x-*`) を利用してカス タム定義を追加可能 `oneOf` / `anyOf` などの新機能を利 用可能
  7. 24 OpenAPI と Swagger の違い 柔軟な設計をするために OpenAPI 使った方が良さそうかな 機能 Swagger

    OpenAPI content によるリクエストボディの柔軟な定義 ❌ ✅ oneOf / anyOf のサポート ❌ ✅ cookie パラメータ ❌ ✅ servers によるエンドポイント管理 ❌ ✅ links によるレスポンスの関係性定義 ❌ ✅
  8. 27 2023年4月6日 4月18日 5月4日 2024年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 対応 本格的に使えそうな兆し! 爆誕! ※ユニオン型など未対応
  9. 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 に対応していない ... 開発自体は行われているが 全体的にリリースがおそい...
  10. 30 2023年4月6日 4月18日 5月4日 2024年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 対応 本格的に使えそうな兆し! 爆誕! ※ユニオン型など未対応
  11. 33 想定質問集 • Go からリプレイスしたらどうするの? • コメントで記述しているとミスらない? • OpenAPI から

    Go のコードを生成するものもあるんじゃないか? 多分こんなこと思ったんじゃないでしょうか?
  12. 34 • その時はその時として割り切っている ◦ リプレイス前に OpenAPI ファイルを生成 ▪ 別言語でも同じことができる物を探す ▪

    もしくは真似てつくる... ◦ 愚直に OpenAPI を書くようにする ▪ スキーマの分割に勤しむ 想定質問集 Go からリプレイスし たらどうする?
  13. 35 • 言いたいことめっちゃよくわかる〜 ◦ デメリット ▪ 記述ミス、ファイルの確認が必要 ◦ メリット ▪

    コードで完結すること ▪ swagger ui にアクセスしながら確認できる ▪ コードベースで記述できるので逆に間違えにくい? • e.g. API レスポンスに使う json タグ 想定質問集 コメントで記述して いるとミスらない?
  14. 36 • あります! ◦ ogen や oapi-codegen がある ▪ バイセルとして

    oapi-codegen 使っているプロダクト もあります ◦ おーたかさんの記事を参考にしてください ◦ https://zenn.dev/otakakot/articles/43653194 611d42 想定質問集 OpenAPI から Go のコードを生成する ものもあるんじゃな いか?
  15. 38 まとめ OpenAPI を吐き出すために使うのは道半ば • 各種フレームワークが swaggo/swag/v2 に未対応 ◦ 今後にめっちゃ期待!

    • とはいえ swaggo/swag 自体は便利だし良い! ◦ orval との連携で拡張性をもたせるために OpenAPI を検討しているだけ ◦ 一旦は Swagger で吐き出し → orval で API クライアントコード出力 アノテーションを活かして記述できるのが個人的に楽 • とはいえ課題感アリ ◦ swaggo/swag のアノテーションについて詳しくなる必要がある ◦ 意図した記述になっているか逐一 generate して確認する必要がある ▪ レビュアーの負担にならないように注意する必要
  16. 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