【26新卒研修】OpenAPI/Swagger REST API研修

Transcript

1. OpenAPI / Swagger REST API 研修 窓⼝から「絶対に破れない契約」へ dip Engineering Training 2026
2. 研修の⽬的 配属後、チームのAPI仕様を⾃⼒で読み解き、実装に落とし込めるようになる 1 読める 既存のOpenAPI定義を⾒て、 エンドポイントの役割‧ リクエスト/レスポンスの構造‧ 制約を正確に把握できる 2 書ける 新しいAPIや既存APIの変更を OpenAPIで記述でき、 Swagger UIで動作確認できる
3. RESTやOpenAPIの 歴史を知ろう
4. ① そもそもAPIとは？ APIの本質を、レストランの「メニュー表」に例えて考えてみましょう。 客（フロントエンド） 料理を注⽂する⼈ API（メニュー表） 両者を繋ぐ 「唯⼀の⼿段」 シェフ（バックエンド） 裏で料理を作る⼈ キーワード：「疎結合（そけつごう）」 客はシェフの調理法を知らなくても、メニューさえあれば料理を受け取れます。 メニューという「境界線」が、お互いの⾃由と安全を守ります。
5. 「密結合」vs「疎結合」 密結合（地獄） メニューがない状態 客が厨房に⼊り込んで 「あのフライパンで焼いて」 と直接指⽰する状態。 シェフが道具を変えただけで 客の指⽰はエラーになる 疎結合（正義） メニューがある状態 「ハンバーグ」と頼むだけ。 シェフは隠し味を変えても、 DBのテーブル名を変えても問題なし。 メニューという「境界線」が お互いの⾃由と安全を守る
6. 「密結合」vs「疎結合」 密結合（地獄） メニューがない状態 客が厨房に⼊り込んで 「あのフライパンで焼いて」 と直接指⽰する状態。 シェフが道具を変えただけで 客の指⽰はエラーになる 疎結合（正義） メニューがある状態 「ハンバーグ」と頼むだけ。 シェフは隠し味を変えても、 DBのテーブル名を変えても問題なし。 メニューという「境界線」が お互いの⾃由と安全を守る APIは疎結合が嬉しい
7. ② APIの歴史：カオスから契約へ 1 創世記（1990年代）：密結合の時代 CORBA, DCOM, (SOAP)… OSやバイナリレベルでの深い互換性が求められ、特定の複雑な設定を双⽅に合わせないと 通信すらできない、極めて「密結合」な時代でした。 2 RESTの普及（2000年代〜）：疎結合を現実にした⾰命 REST 「Webブラウザと同じ仕組み（HTTP）を使えば、もっと楽に繋がる」という設計思想が主流に。
8. RESTの普及：URLとメソッドだけで繋がる 疎結合の理想をWebに応⽤。URLとHTTPメソッドだけでやり取りできる世界へ。 REST API エンドポイント例 GET /jobs 求⼈取得 POST /entries 応募送信 成功の理由 疎結合の理想をWebに応⽤し、URLとメソッド（GET/POSTなど）だけでやり取りできる 環境を整えた。シンプルさが爆発的な普及を⽣んだ。
9. 仕様書迷⼦時代：ドキュメントと実装が乖離する 通信は楽になった。しかし使い⽅はWiki等の「⼈間向けのメモ」で管理されていた。 悲劇：ドキュメントが「嘘」になる 実装（コード）は進化するのに、Wikiの更新が忘れられ、ドキュメントと実態が乖離してしまう。 必須のはずの項⽬が⼊っていない キー名がドキュメントと違う 仕様書がどこにあるか分からない
10. 仕様書迷⼦時代：ドキュメントと実装が乖離する 通信は楽になった。しかし使い⽅はWiki等の「⼈間向けのメモ」で管理されていた。 悲劇：ドキュメントが「嘘」になる 実装（コード）は進化するのに、Wikiの更新が忘れられ、ドキュメントと実態が乖離してしまう。 必須のはずの項⽬が⼊っていない キー名がドキュメントと違う 仕様書がどこにあるか分からない 「厳格な契約」「⾃動化」 が求められた
11. 誕⽣ Swagger/OpenAPI
12. Swagger → OpenAPI：契約のプログラム化 「⼈間向けのメモ」を「マシンが読める設計図」に変えよう、という発想。 Swagger（2011年〜） もともとは特定のツール名。 開発現場の苦労から「コードとドキュメントを⼀ 体化したい」 という動機で誕⽣。 OpenAPIの「⽣みの親」であり前哨戦 OpenAPI（2015年〜） Swaggerの「書き⽅のルール」が業界標準として独⽴。 世界中のエンジニアが同じルールで APIを定義できるように。 YAML/JSONで記述する「設計図」 単なるメモから「設計図」に変わったことで、1つのYAMLファイルから複数の恩恵を同時に得られるように
13. OpenAPI（YAML）のコード例 openapi-spec.yaml paths: /users/{id}: get: summary: ユーザー情報取得 responses: '200': content: application/json: schema: $ref: '#/.../User' components: schemas: User: type: object required: [name] properties: name: { type: string } age: { type: integer } ← これが「絶対の契約」
14. Swagger UI の表⽰例
15. OpenAPIがもたらす「3つの魔法」 1つのYAMLファイルから、以下の恩恵を同時に得られます。 視覚化 嘘をつかないドキュメント Swagger UI YAMLを読み込むだけで、ブラウザ上 でAPIを試せる画⾯が⾃動⽣成され る。 堅牢化 型の⾃動⽣成 TypeScript YAMLから型定義を⾃動⽣成。スペル ミスや認識齟齬がゼロに。 並⾏化 モックサーバーの即時起動 Mock Server バックエンド未完成でも「偽物のサー バー」を⽴てられる。フロントとバッ クが同時に⾛り出せる。
16. 【図解】1つのYAMLから広がるエコシステム openapi.yaml 1つの設計図 Swagger UI ブラウザで⾒れる APIドキュメント 型定義 型安全なコードを⾃動⽣成 Mock Server 偽サーバーで 並⾏開発
17. 【図解】APIの進化タイムライン 1990s CORBA DCOM 密結合 バイナリ依存 2000s SOAP XMLベース まだ複雑 2000〜 REST HTTP + URL シンプル⾰命 2011〜 Swagger ドキュメント ⾃動⽣成 2015〜 OpenAPI 業界標準 絶対の契約 まだ複雑… シンプルに！ ⾃動化！ 標準化！ 密結合 → 疎結合 → ⾃動化 → 標準化 歴史の流れは「より楽に、より安全に繋がる」⽅向へ⼀貫して進んできた
18. 【整理】REST‧OpenAPI‧Swagger の違い この3つは混同しやすいが、それぞれ「レイヤー」が違います。 REST 通信スタイル APIの「設計思想」 URLとHTTPメソッド （GET/POST等）で リソースを操作する という考え⽅そのもの。 たとえると… 「注⽂は⼝頭で 1品ずつ」というルール OpenAPI 仕様（規格） APIの「設計図のフォーマット」 RESTで作ったAPIを YAML/JSONで 正確に記述するための 業界標準ルール。 たとえると… 「メニュー表の書式」 ＝ 全店舗共通テンプレ Swagger ツール群 OpenAPIを「使う」ための道具箱 Swagger UI（閲覧） Swagger Editor（編集） Swagger Codegen（⽣成） などのツール集。 たとえると… 「メニュー表を 印刷する印刷機」
19. ③ なぜ「REST + OpenAPI」なのか GraphQLの⽐較（CTO戦略） GraphQLは柔軟だが、設計や更新処理が複雑。 「全員が迷わず、堅実に作れること」を優先し、世界中で最も普及しているRESTを OpenAPIでガチガチに固める戦略をとっている。 結論 最もエコシステム（便利なツール）が充実しており、 学習コストを抑えつつ最⼤の堅牢性を得られるのが、この組み合わせ。
20. ④ フロントを守り抜く「絶対のルール」 【図解】SoE / SoR 分離アーキテクチャ SoE（System of Engagement） ユーザーに触れる層 Web フロントエンド モバイルアプリ BFF（中間サーバー） O p e n A P I 絶対の 契約 SoR（System of Record） データを守る層 マイクロサービスA マイクロサービスB データベース群 裏側を丸ごと⼊れ替えても、「契約（OpenAPI）」さえ守ればフロントは壊れない
21. ④ フロントを守り抜く「絶対のルール」 「絶対の契約（スキーマ）」 裏側のシステムを丸ごと⼊れ替えても、フロントが壊れないのは、 双⽅が「OpenAPIという共通ルール」を守っているから。 ビジネスを⽌めない武器 裏側の完成を待たずに、先に「契約（OpenAPI）」だけを決めてしまえば、 フロントとバックエンドは同時に開発をスタートできる。
22. ⑤ ⾃⾛するエンジニアになるために 「⾃⾛」＝ 誰かに聞く前に⾃⼒で仕様を読み解き、実装に落とし込める⼒ この後のハンズオンの⽬標 読解⼒ YAMLを⾒てTypeScriptの型を イメージできる 設計⼒ 新しい機能を「契約」から 定義できる スピード感 仕様ファーストで並⾏開発を 体感する
23. OpenAPIを 使いこなそう💪
24. 取り組んでいただく 課題
25. スポバのお仕事コンテキストのOpenAPI仕様書 https://github.com/dip-inc/training-for-new-grads-2026/blob/main/day1/API%E8%A8%AD%E8%A8% 88/api-handson/api/job.yaml
26. このエンドポイントを実⾏して求⼈を作ってみよう！
27. そして、
28. 新しいAPIを定義して、 スポットバイトルに貢献してもらいます！
29. セットアップ