APIファーストの開発

Transcript

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

   View Slide

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

   View Slide

3. 最近のできごと
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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)
    

    View Slide

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

    View Slide