Slide 1

Slide 1 text

もう僕は OpenAPI を書きたくない Go Connect #5 2025. 02. 19

Slide 2

Slide 2 text

2 自己紹介 Sugar Sato (@satoIsSugar) ● 2023年 BuySell Technologies入社 ● 基盤チーム (Portal/Account/Approval) ○ アソシエイトマネージャー ○ PjM ○ プレイングマネージャー ● Go / Angular / Serverless ● 熱帯植物 ○ ビカクシダ ● 猫 ○ Lambda (♀ 2才)

Slide 3

Slide 3 text

3 プロダクト群「バイセルリユースプラットフォーム Cosmos」の開発が進行中 リユースに必要なすべての機能を提供する 「リユースプラットフォーム Cosmos」の開発が進行中です。 Cosmosを活用して、バイセルグループ全体での業務効率改善やデータドリブン経営の深化を目指しています。 リユースプラットフォーム Cosmos 自社開発のリユース特化業務基幹システムでありサービス群の集合体 買取申込 買取・査定 在庫管理 販売 多様なチャネルで収益最大化 CRM -顧客対応- 買取種別に応じた最適なシステム構築 Visit -訪問買取 - Store -店舗買取 - Promas -商材マスタ - Appraisal -専門査定 - Stock -在庫管理 - EXS -販売管理 - Core -会員管理- Portal -データ利用- Pocket -データ基盤- 買取 専門チームによる真贋・査定と連携 査定 申込 効率的な顧客対応 在庫 在庫管理の最適・効率化 販売 データ 各事業プロセスにある データを一元管理 :基幹システム

Slide 4

Slide 4 text

OpenAPIを書くのは好きか〜?

Slide 5

Slide 5 text

僕は正直、面倒だなって感じてます...

Slide 6

Slide 6 text

ということで REST API の開発生産性をあげられそうな話をします

Slide 7

Slide 7 text

01 swaggo/swag とは 02 orval との連携 03 想定質問集 04 まとめ 目次 Index

Slide 8

Slide 8 text

swaggo/swag とは 01

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

10 Star History

Slide 11

Slide 11 text

11 コード

Slide 12

Slide 12 text

12 コード

Slide 13

Slide 13 text

13 コード

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

これらを踏まえて以前にこんな記事を書いた

Slide 16

Slide 16 text

16 以前に書いた記事

Slide 17

Slide 17 text

スキーマ定義だけではなくて API クライアントコードを自動生成できたら楽だな

Slide 18

Slide 18 text

orval との連携性 02

Slide 19

Slide 19 text

時は流れ バイセルに転職後...

Slide 20

Slide 20 text

Swagger / OpenAPI から FE のコードを自動生成できるライブラリがあるらしい

Slide 21

Slide 21 text

21 orval とは ● OpenAPI v3 / Swagger v2 から API クライアントコード生成 ○ yaml や json 対応 ● FE ライブラリやフレームワークとの統合 ○ React / Angular / Vue / Svelte ● CLI で簡単に実行できる Generate client with appropriate type-signatures これが自分のやりたかったことだ〜! swag と合わせて楽できそう?

Slide 22

Slide 22 text

orval を使うにあたって OpenAPI と Swagger の違いを整理する

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

24 OpenAPI と Swagger の違い 柔軟な設計をするために OpenAPI 使った方が良さそうかな 機能 Swagger OpenAPI content によるリクエストボディの柔軟な定義 ❌ ✅ oneOf / anyOf のサポート ❌ ✅ cookie パラメータ ❌ ✅ servers によるエンドポイント管理 ❌ ✅ links によるレスポンスの関係性定義 ❌ ✅

Slide 25

Slide 25 text

なるほど🧐 swaggo/swag で OpenAPI が出力できるんだよ ね?

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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 対応 本格的に使えそうな兆し! 爆誕! ※ユニオン型など未対応

Slide 28

Slide 28 text

本格的に v2 が使えそうな 兆しがみえてきたけど課題もちらほら...

Slide 29

Slide 29 text

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 に対応していない ... 開発自体は行われているが 全体的にリリースがおそい...

Slide 30

Slide 30 text

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 対応 本格的に使えそうな兆し! 爆誕! ※ユニオン型など未対応

Slide 31

Slide 31 text

現状使うとしたら Swagger として出力した方が良さそうかも

Slide 32

Slide 32 text

想定質問集 03

Slide 33

Slide 33 text

33 想定質問集 ● Go からリプレイスしたらどうするの? ● コメントで記述しているとミスらない? ● OpenAPI から Go のコードを生成するものもあるんじゃないか? 多分こんなこと思ったんじゃないでしょうか?

Slide 34

Slide 34 text

34 ● その時はその時として割り切っている ○ リプレイス前に OpenAPI ファイルを生成 ■ 別言語でも同じことができる物を探す ■ もしくは真似てつくる... ○ 愚直に OpenAPI を書くようにする ■ スキーマの分割に勤しむ 想定質問集 Go からリプレイスし たらどうする?

Slide 35

Slide 35 text

35 ● 言いたいことめっちゃよくわかる〜 ○ デメリット ■ 記述ミス、ファイルの確認が必要 ○ メリット ■ コードで完結すること ■ swagger ui にアクセスしながら確認できる ■ コードベースで記述できるので逆に間違えにくい? ● e.g. API レスポンスに使う json タグ 想定質問集 コメントで記述して いるとミスらない?

Slide 36

Slide 36 text

36 ● あります! ○ ogen や oapi-codegen がある ■ バイセルとして oapi-codegen 使っているプロダクト もあります ○ おーたかさんの記事を参考にしてください ○ https://zenn.dev/otakakot/articles/43653194 611d42 想定質問集 OpenAPI から Go のコードを生成する ものもあるんじゃな いか?

Slide 37

Slide 37 text

まとめ 04

Slide 38

Slide 38 text

38 まとめ OpenAPI を吐き出すために使うのは道半ば ● 各種フレームワークが swaggo/swag/v2 に未対応 ○ 今後にめっちゃ期待! ● とはいえ swaggo/swag 自体は便利だし良い! ○ orval との連携で拡張性をもたせるために OpenAPI を検討しているだけ ○ 一旦は Swagger で吐き出し → orval で API クライアントコード出力 アノテーションを活かして記述できるのが個人的に楽 ● とはいえ課題感アリ ○ swaggo/swag のアノテーションについて詳しくなる必要がある ○ 意図した記述になっているか逐一 generate して確認する必要がある ■ レビュアーの負担にならないように注意する必要

Slide 39

Slide 39 text

swaggo/swag 伸び代ですねぇ

Slide 40

Slide 40 text

Thank You

Slide 41

Slide 41 text

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