Stoplight Studioではじめる スキーマ駆動開発 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21

自己紹介 村上 直 株式会社SHIFT で CAT（テスト管理ツール） サービス&テクノロジー本部 技術統括部 開発支援プロダクト推進部 CAT開発室 時系列（降順） 茨城で研究所 DevOps （設計開発導入、セキュリティ、サーバ構築） 研究 六本木ヒルズでガラケーサイト開発 渋谷でシステムコンサル屋 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 2

背景 社内既存プロダクト、基盤へと統合し相乗効果出したい テスト管理、業務管理、教育コンテンツ、、、 技術選定、プロダクト開発：0 → 1 な開発 データを再利用化していきたい REST API開発が大量発生 現在Node.js、expressを使って開発中 3ヶ月で約100本のAPI開発本数が必要 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 3

REST API開発の課題 定義と実装 API定義書と実装がズレる API定義書の記述があいまいで実装依存が発生 バリデーション処理 面倒！ 入出力が階層構造をもつことが多い わずかなIF変更がAPI利用者側に影響 小さな綻びが積み重なってくる → 大きくなって取り返しがつかない！ Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 4

どうすると楽になるか：乖離を避ける 設計 → {ドキュメント、実装、バリデーション、テスト} としたい API設計と定義書作成を同時にしたい API実装側に設計結果を機械的に適用したい API設計結果をそのままテストに（略 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 5

YAML JSON ⽣成 ⽣成 利⽤ ⽣成物の YAML/JSON が利⽤され、 妥当性チェックが働いている • REST API⼊出⼒設計 • GUI ⇔ CUI • ⼊出⼒バリデーション • ⾃動テスト • APIリファレンス⽣成 OpenAPI規格のエコシステムに乗ろう︕ DRYに⾏こう︕ OpenAPI Document Donʼt Repeat Yourself! Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 6

Stoplight Studio OpenAPI（Swagger）形式に準拠 REST API入出力設計をGUIで行える URL pathやパラメータをGUIにて入力 → 対応するYAMLが階層構造でザクザクと生成される GUI(煩雑) と CUI(複雑) を行き来できる GUI: 構文やパラメータ名など CUI: 中身を埋めるなど 安心感: 複雑化するYAMLが常に構文チェックされる プレビュー: YAMLの全体構造を見渡す Mac版、Windows版、Web版、Linux版 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 7

express-openapi-validator Node.js、Expressフレームワーク用のライブラリ まさに DRY：OpenAPI設計をインポート バリデーション指定として直接使える 強力なデフォルト設定 インポートしたOpenAPIに無い変数名をはじく TypeScriptの場合、型に合わない入力値をはじく APIの入力・出力両方にバリデーションを適用できる 複雑なOpenAPIファイルにも対応 2019年のリリース以降、開発が進んでいる Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 8

jest-openapi Node.js、Jestテストフレームワーク用のライブラリ OpenAPIを指定するとAPI出力結果の検証を行ってくれる 複雑な書式には対応せず 2020年リリース、開発途上 Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 9

ReDoc APIリファレンス生成ライブラリ OpenAPIを指定 → 手軽にAPIリファレンスを生成 リファレンスを利用者に早めに展開できる レスポンシブデザイン対応：麗しい出来栄え Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 10

取り組みの結果 開発効率が大きく向上 約3ヶ月でAPI開発本数は100本 自動テスト開発もコミコミ 開発者本人は夏休み取得中！ まだ200本以上ある 自分たちで技術選定＋ゼロイチで造る エンジニア汁出まくり！ 仲間がほしい！ Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 11

取り組みの結果 開発効率が大きく向上 約3ヶ月でAPI開発本数は100本 自動テスト開発もコミコミ 開発者本人は夏休み取得中！ まだ200本以上ある 自分たちで技術選定＋ゼロイチで造る！ エンジニア汁出まくり！ 仲間がほしい！ Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 12

ご清聴ありがとうございました エンジニア募集中です！ Stoplight Studioではじめるスキーマ駆動開発 　　　　　　　SHIFT EVOLVE LT会 Vol.4 「小さなものから大きなものまで 開発あるある」　　2021-09-21 13