APIファーストの開発

Transcript

1. API主体のアプリケーション開発
2. About me 名前：川合 亮 所属：株式会社リアルグローブ・オートメーティッド
3. 最近のできごと
4. きっかけ • APIはあるがドキュメントがない ◦ コードサンプルからどういうリクエストを送ったらいいか試行 ◦ レスポンスは実際に送られてきたデータを見て型をチェック • APIを1つ追加する際に多くの変更が必要 ◦ バグのとき、フロントエンド、バックエンドそれぞれどちらが間違っているか難しい • ドキュメントと実装が乖離している
5. スキーマファーストをやってみました スキーマファーストとは • API仕様を中心にバックエンド、フロントエンドの開発を並行して行う方法 • OpenAPIを用いることが多い。(RESTful APIをYAML/JSONで定義したもの) • 周辺ツールが発達している ◦ コード生成ツール（API変更時の負担軽減） ◦ モックサーバー、ドキュメント生成
6. OpenAPIの例 • YAML/JSON形式で記載したテキストファイル • REST API準拠で定義する • リクエスト、レスポンスの型を定義、指定できる • 昔はSwagger、現在最新はv3.1 (v3.0使うほうが無難) OpenAPI Initiative (https://www.openapis.org/) スキーマ設計おすすめサイト (https://future- architect.github.io/articles/20200409/)
7. OpenAPIの例 Swagger Editor (https://editor.swagger.io/) ReDoc (https://redocly.github.io/redoc/)
8. APIドキュメントからできることについて APIドキュメン ト コードジェネレータ モックサーバー Goなどのコード • ハンドラなど生成 • 型定義で誤りにくい モックサーバー • サンプル値のレスポンスを返す APIサーバーが立てれる • APIサーバーを待たずにフロン トエンド開発ができる
9. OpenAPIの書くときのツール • YAML力が必要 • 長大になりがち
10. Stoplight Studioについて • GUIで作成できるツール • 構文間違いのお知らせあり • マルチプラットフォーム https://stoplight.io/p/studio/gh/stoplightio/studio
11. Prismについて • APIドキュメントを元に ◦ モックサーバーの起動 ◦ アプリの動作検証 https://stoplight.io/p/studio/gh/stoplightio/studio
12. コード生成について • openapi-codegenerator (https://github.com/OpenAPITools/openapi-generator) ◦ おそらくコードジェネレータのデファクトスタンダード ◦ 相当数の言語に対応している ◦ 言語毎の品質はまばら • kin-openapi (https://github.com/getkin/kin-openapi) ◦ Goのコードジェネレータ ◦ レスポンスのバリデートが実装されている • restful-react (https://www.npmjs.com/package/restful-react) ◦ Reactのfetch部分などのコードジェネレータ ◦ Reactで使うならこちらの方が楽かも その他サポートしているツールリスト https://github.com/OAI/OpenAPI-Specification/blob/main/IMPLEMENTATIONS.md
13. 実際にやってみたこと サンプルアプリケーションを作成 ブログのように記事の一覧、作成を行うシンプルなアプリケーションで利用 バックエンドはGo + echo (oapi-codegen) で実装 フロントエンドはReact + Typescript (openapi-codegenerator)で実装 APIドキュメントがないアプリケーションでドキュメント作成 コードベースでリクエスト、レスポンスのデータ型をドキュメントにした ReDocなどで他の人が閲覧しやすいようにした
14. 所感 • メリット ◦ バックエンド、フロントエンドからのデータを疑う必要がない ◦ コード生成による変更負担減 ◦ ドキュメントがあるのでどういったデータを送ればいいか連携しやすい • デメリット ◦ OpenAPIの学習コスト、メンテナンスコスト（GUIツールがあっても） ◦ コード生成ツールの選定に時間がかかる ◦ 周辺ツールを上手く使って開発に組み込む必要がある
15. OpenAPI ドキュメントが使用できるクラウドサービ ス • AWS ◦ Amazon API Gateway (https://aws.amazon.com/jp/api-gateway/) • Azure ◦ Azure API Management (https://azure.microsoft.com/ja-jp/services/api-management/) • GCP ◦ Cloud Endpoint (https://cloud.google.com/endpoints)
16. ご清聴ありがとうございました