PHPパッケージにバグ見つけちゃいました...
composerでインストール可能なPHPパッケージを使用していて、
どうも期待通りに動かない箇所がありました。
バグ発見、応急処置、最終的にパッケージ更新までの流れをまとめてみました。
期待通りに動かない??
cakephp-swagger-bake
というCakePHPとswaggerの橋渡しするようなパッケージを使用して、
高速にREST API開発&テスト環境(Swagger UI)構築を進めてました。
シンプルなAPIについては、あまり調整はいらないのですが、
複雑なリレーションなどを含むAPIの場合、アノテーションを使って微調整する必要があります。
今回はそのアノテーション処理周りで、OpenAPI仕様からずれた出力がされるケースがあり、
Swagger UI 上で、テストをしようとするとResponsesのExample values が期待通りに
出力されなかったです。
バグ発見
Swagger UIで見ていてもよくわからないので、以下の手順で問題箇所の特定を進めました。
- アノテーションの書き方を調整してswagger.jsonの出力調整
- swagger.jsonを手動書き換えして結果の変化を確認する
- swagger.jsonを出力する箇所のPHPコードの確認
- OpenAPIの仕様との照らし合わせ
結論として、今回出力しようとしたリレーションの場合、OpenAPI仕様ではおかしい形式になっていたため、正常に動作してませんでした。
応急処置
パッケージ本体に問題があったので、
- パッケージをオーバーロードするような別パッケージを用意する
- パッケージを手動で修正する
という二つの方法を検討しました。
今回の修正箇所については、1つのクラスの1メソッドなので、オーバーロードも可能といえば可能です。ただ、メソッドをオーバーロードするのは向いてないコードでしたので、メソッドは差し替えになります。
となるとバージョンアップ耐性が低い!
ということで、パッケージを手動で修正することにしました。
パッケージ修正の永続化
インストール毎、パッケージのアップグレード毎に手作業をするのは不安定すぎるので、
パッチ作成、自動パッチ適用をすることにしました。
修正後ファイルをnewsrc/Lib/Operation/OperationResponse.php に作成してから
パッチファイル作成
mkdir patches
diff -ubB src/Lib/Operation/OperationResponse.php newsrc/Lib/Operation/OperationResponse.php > patches/cakephp-swagger-bake-ref-array.patch
パッチファイルは
--- src/Lib/Operation/OperationResponse.php 2023-03-03 03:35:07.000000000 +0900
+++ newsrc/Lib/Operation/OperationResponse.php 2023-03-03 03:36:41.000000000 +0900
@@ -115,9 +115,16 @@ class OperationResponse
private function addResponseRef(Response $response, string $mimeType, OpenApiResponse $openApiResponse): bool
{
if ($openApiResponse->ref) {
- $schema = (new Schema())
- ->setAllOf([['$ref' => $openApiResponse->ref]])
- ->setType($openApiResponse->schemaType);
+ if ($openApiResponse->schemaType == 'array') {
+ $schema = (new Schema())
+ ->setItems(['$ref' => $openApiResponse->ref])
+ ->setType($openApiResponse->schemaType);
+ }
+ else {
+ $schema = (new Schema())
+ ->setAllOf([['$ref' => $openApiResponse->ref]])
+ ->setType($openApiResponse->schemaType);
+ }
$response->pushContent(new Content($mimeType, $schema));
$this->operation->pushResponse($response);
続いて、パッチを自動適用するためのパッケージの追加
https://packagist.org/packages/cweagans/composer-patches
composer install cweagans/composer-patches
パッケージ適用するためのファイルを定義します。
patches/update.json
{
"patches": {
"cnizzardini/cakephp-swagger-bake": {
"update ref/array problem": "patches/cakephp-swagger-bake-ref-array.patch"
}
}
}
これで自動適用できるようになりました。
バグ報告
今回は明確にバグで困ってる人もいそうなので、バグ報告&修正パッチの送信をすることにしました。
https://github.com/cnizzardini/cakephp-swagger-bake/issues
New issueを押して
タイトルと本文を入力する画面になります。
タイトルはできるだけ具体的にパッケージのメンテナーの方にわかるように意識して書きました。
本文では以下の5項目を指示通りに記載します。
- Describe the bug バグの説明
- To Reproduce 再現条件
- Expected behavior 期待される動作
- Version and Platform (please complete the following information) 確認した環境
- Additional context 追記事項
実例は
https://github.com/cnizzardini/cakephp-swagger-bake/issues/512
をご覧ください。
修正報告
Issue登録後、パッチの送信を準備します。
- レポジトリのFork
- ローカル環境にc
- Branchを切る
- 修正をcommit / push
- プルリクエスト
その後のやりとり
定められたテストが不十分で、プルリクがリジェクトされてました。
修正後、composer analyzeでコードのチェック、問題箇所を修正しました。
修正内容
- コードのフォーマットの統一
- テストコードの修正(今回はテストコード自体間違ってましたので)
無事リリース
https://github.com/cnizzardini/cakephp-swagger-bake
https://packagist.org/packages/cnizzardini/cakephp-swagger-bake