API主体のアプリケーション開発

About me 名前：川合 亮 所属：株式会社リアルグローブ・オートメーティッド

最近のできごと

きっかけ ● APIはあるがドキュメントがない ○ コードサンプルからどういうリクエストを送ったらいいか試行 ○ レスポンスは実際に送られてきたデータを見て型をチェック ● APIを1つ追加する際に多くの変更が必要 ○ バグのとき、フロントエンド、バックエンドそれぞれどちらが間違っているか難しい ● ドキュメントと実装が乖離している

スキーマファーストをやってみました スキーマファーストとは ● API仕様を中心にバックエンド、フロントエンドの開発を並行して行う方法 ● OpenAPIを用いることが多い。(RESTful APIをYAML/JSONで定義したもの) ● 周辺ツールが発達している ○ コード生成ツール（API変更時の負担軽減） ○ モックサーバー、ドキュメント生成

OpenAPIの例 ● YAML/JSON形式で記載したテキストファイル ● REST API準拠で定義する ● リクエスト、レスポンスの型を定義、指定できる ● 昔はSwagger、現在最新はv3.1 (v3.0使うほうが無難) OpenAPI Initiative (https://www.openapis.org/) スキーマ設計おすすめサイト (https://future- architect.github.io/articles/20200409/)

OpenAPIの例 Swagger Editor (https://editor.swagger.io/) ReDoc (https://redocly.github.io/redoc/)

APIドキュメントからできることについて APIドキュメン ト コードジェネレータ モックサーバー Goなどのコード ● ハンドラなど生成 ● 型定義で誤りにくい モックサーバー ● サンプル値のレスポンスを返す APIサーバーが立てれる ● APIサーバーを待たずにフロン トエンド開発ができる

OpenAPIの書くときのツール ● YAML力が必要 ● 長大になりがち

Stoplight Studioについて ● GUIで作成できるツール ● 構文間違いのお知らせあり ● マルチプラットフォーム https://stoplight.io/p/studio/gh/stoplightio/studio

Prismについて ● APIドキュメントを元に ○ モックサーバーの起動 ○ アプリの動作検証 https://stoplight.io/p/studio/gh/stoplightio/studio

コード生成について ● 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

実際にやってみたこと サンプルアプリケーションを作成 ブログのように記事の一覧、作成を行うシンプルなアプリケーションで利用 バックエンドはGo + echo (oapi-codegen) で実装 フロントエンドはReact + Typescript (openapi-codegenerator)で実装 APIドキュメントがないアプリケーションでドキュメント作成 コードベースでリクエスト、レスポンスのデータ型をドキュメントにした ReDocなどで他の人が閲覧しやすいようにした

所感 ● メリット ○ バックエンド、フロントエンドからのデータを疑う必要がない ○ コード生成による変更負担減 ○ ドキュメントがあるのでどういったデータを送ればいいか連携しやすい ● デメリット ○ OpenAPIの学習コスト、メンテナンスコスト（GUIツールがあっても） ○ コード生成ツールの選定に時間がかかる ○ 周辺ツールを上手く使って開発に組み込む必要がある

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)

ご清聴ありがとうございました