実装と乖離させないスキーマ駆動開発フロー ／ OpenAPI Laravel編

Transcript

1. 実装と乖離させないスキーマ駆 動開発フロー / OpenAPI Laravel 編 Press Space for next page （非公式）PHP Conference Fukuoka After Hack!! June 25, 2023. v0.0.21
2. 自己紹介 以下のアカウントで活動しています katzumiと申します katzchum k2tzumi katzumi
3. スキーマ駆動開発のフローってどうやっていますか？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。
4. スキーマ駆動開発のフローってどうやっていますか？ ドキュメント（スキーマ定義の仕様書）が先？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。
5. スキーマ駆動開発のフローってどうやっていますか？ ドキュメント（スキーマ定義の仕様書）が先？ APIの実装（コード）が先？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。
6. 問題点 スキーマ定義（ドキュメント）と実際の実装（コード）が乖離してしまう
7. なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）
8. なぜ乖離が発生するのか？ コード生成 実装 Open API Spec Stub コード 実際のコード ドキュメントが先の場合（コードが先であっても。。）
9. なぜ乖離が発生するのか？ コード生成 実装 変更 ❌ 変更済みのStub を反映することはできない Open API Spec Stub コード 実際のコード * ドキュメントが先の場合（コードが先であっても。。）
10. なぜ乖離が発生するのか？ コード生成 実装 変更 ❌ 変更済みのStub を反映することはできない 変更 ❌ 定義が間違っていても自動反映はされない Open API Spec Stub コード 実際のコード * * ドキュメントが先の場合（コードが先であっても。。）
11. なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）
12. なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）
13. なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）
14. つらい、、
15. なぜ？
16. スキーマとコードとの距離が離れてしまっている コード生成 実装 ココ!! Open API Spec Stub コード 実際のコード 独立したものになっていて、乖離が発生したことを見落としがち
17. どうすれば距離が縮まるか？
18. スキーマ定義をコードに埋め込むという方法 swagger-php のAttributeを使ってスキーマを定義する Controller <?php use OpenApi\Attributes as OA; #[OA\Info(title: "My First API", version: "0.1")] class OpenApi {} class MyController { #[OA\Get(path: '/api/data.json')] #[OA\Response(response: '200', description: 'The data')] public function getResource() { // ... } } Request <?php use OpenApi\Attributes as OA; use Illuminate\Foundation\Http\FormRequest; #[OA\Schema(schema: 'CreateUserRequest', title: ' ユーザー生成のリクエ class CreateUserRequest extends FromRequest { use BaseRequestTrait; #[OA\Property('username', description: ' ユーザー名', type: 'string', maxLength: 100, pattern: '^[a-zA-Z\d]{4,100}', example: 'scott', nullable: false)] public string $username; #[OA\Property('email', description: ' メールアドレス', type: 'string', maxLength: 320, pattern: '^[a-zA-Z0-9_.+-]+@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA- example: 'abc@example.com',nullable: false)] public string $email;
19. レビューしやすい 視点移動が少なくて済む
20. 絶対スキーマから乖離させないマン Attributeや実際に出力されたスキーマファイルを活用してスキーマとコードを乖離させない仕組み
21. Attributeの力を引き出してみる!
22. Arttibuteはコードの一部！ ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする
23. Arttibuteはコードの一部！ 生成 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 Controller クラス Request クラス Response クラス スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする
24. Arttibuteはコードの一部！ 生成 ズレが発生しない 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする
25. Arttibuteはコードの一部！ 生成 ズレが発生しない 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする
26. スキーマ自体も静的解析すべし！ OpenAPI Spec 表示 生成 静的解析 整形 require スキーマファイル spectral Redoc 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル swagger-php(L5-Swagger) swagge-ui
27. リクエスト・レスポンスの正確性を保証させる 生成 参照（リクエスト・レスポンスValidation ） テスト実行 Test コード Use laravel-openapi-validator Controller テスト(PHPUnit) 実際のコード 自動生成 実行時評価 Route ファイル Controller クラス Request クラス Validation ルール Response クラス スキーマファイル Controllerテストで laravel-openapi-validator を利用してリクエストとレスポンスを検証
28. より確実にE2Eで検証 生成 参照（リクエスト・レスポンスValidation ） テスト実行 Test コード API シナリオテスト(runn) 実際のコード 自動生成 実行時評価 Route ファイル Controller クラス Request クラス Validation ルール Response クラス スキーマファイル APIシナリオテスト（ runn ）でユースケースを網羅的に検証
29. まとめ
30. スキーマ≠ドキュメント スキーマはコードの一部。ドキュメンテーションツールからSpecを自動生成
31. スキーマをいつ書くか？ コードを書いたら勝手にスキーマ定義がいい感じに出力されている状態
32. スキーマ自体もテストが必要 静的解析して最低限の品質を確保 テストでの検証にも利用してスキーマを含んだAPI自体の品質も向上させる
33. 参考URL 実装と乖離させないスキーマ駆動開発フロー / OpenAPI Laravel編 https://zenn.dev/katzumi/articles/schema-driven-development-flow swagger-php https://github.com/zircote/swagger-php spectral https://github.com/stoplightio/spectral laravel-openapi-validator https://github.com/kirschbaum-development/laravel-openapi-validator runn https://github.com/k1LoW/runn
34. ご清聴ありがとうございます