OpenAPI を用いた GoのAPIサーバー の開発自動化

マネーフォワードのPublic API開発において、OpenAPIを用いてGoのAPIサーバー構築を効率化しました。
利用シーン/技術選定/使ってみての長所短所を記載しています。

Transcript

1. OpenAPIを用いて、GoのAPIサーバー構築を効率化した話
2. 自己紹介
3. • 櫻 勇人(さくら ゆうと) ◦ Twitter: ysakura_ ◦ Go歴は3年ほど • 株式会社マネーフォワード @ 京都開発拠点 ◦ サーバーサイドエンジニア ▪ toB領域を主に担当 ◦ これまで ▪ Go製のマイクロサービスの開発運用 ◦ 最近 ▪ Public APIの開発推進 ▪ OAuth 2.0の認可基盤の開発 自己紹介
4. • MFでのAPI開発 • OpenAPIを採用した理由 • 利用したライブラリの紹介 • MFでの利用シーン • ライブラリの良かった点 / 辛かった点 • 結論 今日話す事
5. • Public APIを絶賛開発中 ◦ 外部のサービスとの連携性向上が目的 ◦ Goのマイクロサービスがある所は GoでAPIを実装 • APIの基盤も構築中 ◦ OAuth 2.0の認可基盤など ◦ こちらは別の機会に MFでのAPI開発
6. • OpenAPI ◦ 特定の開発言語に依存しない標準的な RESTful APIのインターフェース定義 ◦ 例 • スキーマ駆動開発をしたい ◦ 最初にスキーマ(API定義)を作り、それを元に開発を進めること ▪ 社外の人にAPIを使って貰うので、スキーマからスタートしたい ◦ API定義とサーバー実装がズレない様にしたい ▪ 外部に提供しているインターフェイスとずれると困る ▪ スキーマからGoのコードが自動生成される様にしたい • 利用事例が多いものを採用したい OpenAPIを採用した理由
7. https://github.com/deepmap/oapi-codegen • 使い方 利用したライブラリの紹介 go get github.com/deepmap/oapi-codegen/cmd/oapi-codegen oapi-codegen petstore-expanded.yaml > petstore.gen.go
8. https://github.com/deepmap/oapi-codegen • 自動生成されるコードの例 ◦ OpenAPI ▪ petstore-expanded.yaml ◦ 型 ▪ petstore-types.gen.go ◦ handlerのベース実装 ▪ petstore-server.gen.go ◦ クライアント ▪ petstore-client.gen.go 利用したライブラリの紹介
9. MFでの利用シーン • APIサーバー ◦ handlerの自動生成 ◦ 型の自動生成 • テスト ◦ E2Eテストで自動生成されたクライアントを利用
10. • 型の自動生成 ◦ OpenAPIの型(Schema)が、Goの型として自動生成される ▪ petstore-types.gen.go ▪ OpenAPIとサーバー実装のズレが無くなった • handlerのベース実装の自動生成 ◦ ルーターへのhandler登録 (生成例) ◦ パラメーターのパース (生成例) ◦ OpenAPIに基づいたhandlerのInterface(生成例) ▪ このInterfaceを守らないとBuildが失敗する • OpenAPIとサーバー実装のズレが無くなった oapi-codegenで良かった点
11. • クライアントの自動生成 ◦ E2Eテストで用いた ◦ 実装が減り、テスト作成がかなり楽になった ▪ HTTPリクエストの作成など ◦ 実装例 ▪ 初期化 ▪ リクエスト oapi-codegenで良かった点
12. • Validatorが採用出来ず、自前でバリデーションを実装した ◦ OpenAPIを元にしたValidatorが提供されている(実装) ◦ APIサーバーから返るエラーは、自社のエラーフォーマットに沿う様にしたかった ▪ エラー時の文言/JSONを変更できないので、 oapi-codegenのValidatorは利用せず ◦ 今思えば、oapi-codegenのエラーを受け取り、エラーハンドリングすべきだったかも ▪ 後続のmiddlewareで処理する様な形 • APIレスポンスのfieldの並び順が、OpenAPIの並び順と同じにならない ◦ curl等でデバッグする人向けに、重要な情報を上部に表示したかった ◦ OpenAPIの並びをソートして、 Goの構造体が作成される仕様 oapi-codegenで辛かった点
13. • リクエストとレスポンスで同じ型として扱いたいものが、別の型となってしまう ◦ ページネーションなど ▪ Cursor • Parameters ▪ NextCursor • Schema ◦ これはもしかすると、 OpenAPIの使い方が悪いのかもしれない oapi-codegenで辛かった点
14. • スキーマ駆動開発は楽 ◦ OpenAPIを正とした開発の安心感は強い • deepmap/oapi-codegen オススメ ◦ handlerのロジック実装に集中する事が出来た 結論
15. We are hiring! Goを使って、ユーザーの課題を解決したいエンジニアを募集中です！ カジュアル面談から是非