PHPのアノテーション（アトリビュート）からOpenAPIのドキュメントを出力し、レスポンスもそれを元にシリアライズすることで仕様と実装を乖離させず、色々楽できたよって話

1. PHP のアノテーション（アトリビュー ト）からOpenAPI のドキュメントを出 力し、レスポンスもそれを元にシリア ライズすることで仕様と実装を乖離さ せず、色々楽できたよって話 Toshiyuki Fujita (@kalibora) 2024/11/08
2. 最初に 今回の発表は2019 年11 月の KyotoLT 第25 回 で喋った Swagger (OpenAPI) と PHPStan で REST API でも型安全っぽく使う の焼き 直しです でも多分誰も知らないと思うのここでも話します 現状はOpenAPI は3 系ですが、昔の話なので2 系（まだSwagger と呼 ばれてた時代）が話のベースとなっていますがご容赦ください 2024/11/11 追記 この発表後に現代では API Platform を使えばもっといい感じに できると教えていただきました なのでこの資料は過去の歴史としてご笑覧ください
3. 自己紹介 Toshiyuki Fujita ID: @kalibora 20 年くらいPHP いじってご飯を食べてます Yahoo! JAPAN -> (Crocos) -> Otobank -> RABO 今回のは Otobank 時代にやってた話です Symfony と Doctrine が好きです
4. OpenAPI とは - （WebAPI の仕様書くツールって、昔はいろいろあったけど結局もう これが勝ったという認識でよろしいか？） OpenAPI Specification （以前はSwagger Specification として知ら れていた）は、Web サービスを記述、生成、消費[ 訳語疑問点] 、 可視化するための機械可読なインターフェース記述言語の仕様で ある[1] 。 See: https://ja.wikipedia.org/wiki/OpenAPI_Specification “ “
5. 突然ですが・・・ OpenAPI の仕様書くのって ダルいですよね？
6. OpenAPI の仕様書くのってダルいですよね？ swagger: "2.0" info: version: "1.0.0" description: "こういうやつですね" title: "Swagger Petstore" termsOfService: "http://swagger.io/terms/" contact: email: "apiteam@swagger.io" license: name: "Apache 2.0" url: "http://www.apache.org/licenses/LICENSE-2.0.html" host: "petstore.swagger.io" basePath: "/v2"
7. OpenAPI の仕様を書くための手段 Swagger Editor https://editor.swagger.io/ ブラウザベースで記述できるエディター swagger-php https://github.com/zircote/swagger-php PHP のアトリビュート（もしくはアノテーション）を使って仕様 を記述できる これを使って楽する！！ （※これ調べたの昔なので最近はもっと色々増えてるかもね！）
8. swagger-php(v2) の使用例 例えば User というクラスに name プロパティがあって、 これをAPI のレスポンスのI/F として定義したい場合、 /** * @SWG\Definition() */ class User { /** * ユーザー名 * @SWG\Property() */ public string $name; }
9. 出力結果 swagger: '2.0' definitions: User: properties: name: description: ユーザー名 type: string
10. 便利！ でもデフォルトのswagger-php だと 不便な点があった
11. デフォルトのswagger-php だと不便な点 getter などのアクセサに対応していない 実際の業務で使っているエンティティクラスは private なプロパ ティ + getter な構成が多いのでそのままだとうまく使えない （※2024/11/08 現在ではできるようになったのか未確認です） ので、自前で swagger-php を拡張して対応した
12. 自前で swagger-php を拡張して getter に対応 /** * @SWG\Definition() */ class User { private sring $name; /** * ユーザ名 * @SWG\Property() */ public function getName() : string { return $this->name; } }
13. 出力結果 先ほどとほぼ同じ結果のOpenAPI 仕様が書き出されるように拡張。 return type hint を使い、nullable でないものは required に。 swagger: '2.0' definitions: User: required: - name properties: name: description: ユーザー名 type: string
14. いい！！ けどせっかくなら そのままAPI の挙動にも反映したい
15. API の挙動にも反映したい そもそもだけど、アノテーション（アトリビュート）書いたらその ままAPI の挙動に反映できたら便利 アノテーション（アトリビュート）から 仕様（OpenAPI 仕様の出力結果） 実装（実際にレスポンスとして返す値） この両方に影響を与えたい
16. オブジェクトから配列に変換する処理を書いた ようするにシリアライザー（ノーマライザー？）を実装した。 /** * @SWG\Definition() */ class User { private sring $name; /** * ユーザ名 * @SWG\Property() */ public function getName() : string { return $this->name; } } 先ほどと同じこういうクラスの定義から、
17. 連想配列に変換 SwaggerSerializer という自前で実装したクラスが @SWG\Property アノ テーションを読み取り、連想配列にする。 $user = new User('Otobank Taro'); var_dump($swaggerSerializer->serialize($user)); // [name => 'Otobank Taro'] これにより、 @SWG\Property を定義した getter は API のレスポンスの I/F としても露出するし、実際にAPI のレスポンスとしても返却される ようにした。
18. PHPStan と組み合わせる
19. PHPStan と組み合わせる PHPStan と組み合わせれば、サーバー（API ）側とクライアント側 との間でAPI 呼び出しをしても型安全にできる
20. 例えばこんなケース
21. API 側のエンティティクラス class Campaign { /** * キャンペーン開始日時 * @SWG\Property() */ public function getStartedAt() : \DateTimeInterface { /* 実装は省略 */ } /** * キャンペーン終了日時 * @SWG\Property() */ public function getEndedAt() : ?\DateTimeInterface { /* 実装は省略 */ } }
22. 出力されるOpenAPI 仕様書 swagger: '2.0' definitions: Campaign: required: - startedAt properties: startedAt: description: キャンペーン開始日時 type: string format: date-time endedAt: description: キャンペーン終了日時 type: string format: date-time x-nullable: true # ←ここに注目
23. OpenAPI 仕様書から自動生成されたクライアント側のクラス class Campaign implements ModelInterface, ArrayAccess { /** * Gets started_at * @return \DateTime */ public function getStartedAt() { /* 実装は省略 */ } /** * Gets ended_at * @return \DateTime|null */ public function getEndedAt() { /* 実装は省略 */ } } ※ クライアントの自動生成は swagger-api/swagger-codegen をベースに x-nullable を うまく解釈できるようにテンプレートはカスタマイズしています
24. クライアント側のPHPStan でのチェック クライアント側で自動生成されたクラスでも getEndedAt() が nullable なので、API を呼び出す側の実装者が、うっかりキャンペーンの終了日 時が nullable である。 という仕様を知らなかった（読み取りそこねた）としても、自動的に エラーを検出できる。
25. さらにいろんなことに活用できる
26. その他の活用事例 public なAPI がセンシティブな情報を返していないことをCI で担保する 仕様と実装が乖離していないため、仕様であるyaml(or json) ファイルを機械 的にパースして特定のキーワード（password など）がレスポンスにあった らCI で落とす 詳しくは: API が不必要にセンシティブなデータを返していないことをCI で 担保する - OTOBANK Engineering Blog API のI/F 変更があったらサマリをGitHub Actions でPR に書いてもらう OpenAPITools/openapi-diff を使って仕様の差分を取る さらに（プロパティが削除されるなどの理由で）後方互換性が崩れていたら CI で落とす
27. おしまい