Upgrade to Pro — share decks privately, control downloads, hide ads and more …

APIファーストの開発

 APIファーストの開発

532348a1aba5a909e283624c3d2a9a95?s=128

SHIFT_EVOLVE

July 26, 2021
Tweet

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. ご清聴ありがとうございました