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仕様ではおかしい形式になっていたため、正常に動作してませんでした。

応急処置

パッケージ本体に問題があったので、

パッケージをオーバーロードするような別パッケージを用意する
パッケージを手動で修正する
という二つの方法を検討しました。

今回の修正箇所については、１つのクラスの１メソッドなので、オーバーロードも可能といえば可能です。ただ、メソッドをオーバーロードするのは向いてないコードでしたので、メソッドは差し替えになります。
となるとバージョンアップ耐性が低い！

ということで、パッケージを手動で修正することにしました。

パッケージ修正の永続化

インストール毎、パッケージのアップグレード毎に手作業をするのは不安定すぎるので、
パッチ作成、自動パッチ適用をすることにしました。

修正後ファイルを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"
        }
    }
}

これで自動適用できるようになりました。