refactor(validator): address review feedback for content negotiation

Allow failure() to preserve matchedPath so coverage tracking works for
matched endpoints even on validation failures.

Add docblocks to isJsonContentType() and isContentTypeInSpec() with
preconditions. Clarify content negotiation comment to document the
intentional asymmetry between JSON and non-JSON type matching.

Narrow catch(Throwable) to catch(JsonException) in extractJsonBody()
to avoid masking unrelated errors.

Author: wadakatu

src/Laravel/ValidatesOpenApiSchema.php

@@ -5,10 +5,10 @@
 namespace Studio\OpenApiContractTesting\Laravel;
 
 use Illuminate\Testing\TestResponse;
+use JsonException;
 use Studio\OpenApiContractTesting\HttpMethod;
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
 use Studio\OpenApiContractTesting\OpenApiResponseValidator;
-use Throwable;
 
 use function is_string;
 use function str_contains;
@@ -94,7 +94,7 @@ private function extractJsonBody(TestResponse $response, string $content, string
 
         try {
             return $response->json();
-        } catch (Throwable $e) {
+        } catch (JsonException $e) {
             $this->fail(
                 'Response body could not be parsed as JSON: ' . $e->getMessage()
                 . ($contentType === '' ? ' (no Content-Type header was present on the response)' : ''),

src/OpenApiResponseValidator.php

@@ -49,7 +49,7 @@ public function validate(
         if (!isset($pathSpec[$lowerMethod])) {
             return OpenApiValidationResult::failure([
                 "Method {$method} not defined for path {$matchedPath} in '{$specName}' spec.",
-            ]);
+            ], $matchedPath);
         }
 
         $statusCodeStr = (string) $statusCode;
@@ -58,7 +58,7 @@ public function validate(
         if (!isset($responses[$statusCodeStr])) {
             return OpenApiValidationResult::failure([
                 "Status code {$statusCode} not defined for {$method} {$matchedPath} in '{$specName}' spec.",
-            ]);
+            ], $matchedPath);
         }
 
         $responseSpec = $responses[$statusCodeStr];
@@ -71,8 +71,9 @@ public function validate(
         /** @var array<string, array<string, mixed>> $content */
         $content = $responseSpec['content'];
 
-        // When the actual response Content-Type is provided, use it to select
-        // the correct media type entry from the spec (content negotiation).
+        // When the actual response Content-Type is provided, handle content negotiation:
+        // non-JSON types are checked for spec presence only, while JSON-compatible types
+        // fall through to schema validation against the first JSON media type in the spec.
         if ($responseContentType !== null) {
             $normalizedType = $this->normalizeMediaType($responseContentType);
 
@@ -86,10 +87,13 @@ public function validate(
 
                 return OpenApiValidationResult::failure([
                     "Response Content-Type '{$normalizedType}' is not defined for {$method} {$matchedPath} (status {$statusCode}) in '{$specName}' spec. Defined content types: {$defined}",
-                ]);
+                ], $matchedPath);
             }
 
             // JSON-compatible response: fall through to existing JSON schema validation.
+            // JSON types are treated as interchangeable (e.g. application/vnd.api+json
+            // validates against an application/json spec entry) because the schema is
+            // the same regardless of the specific JSON media type.
         }
 
         $jsonContentType = $this->findJsonContentType($content);
@@ -108,7 +112,7 @@ public function validate(
         if ($responseBody === null) {
             return OpenApiValidationResult::failure([
                 "Response body is empty but {$method} {$matchedPath} (status {$statusCode}) defines a JSON-compatible response schema in '{$specName}' spec.",
-            ]);
+            ], $matchedPath);
         }
 
         /** @var array<string, mixed> $schema */
@@ -147,7 +151,7 @@ public function validate(
             }
         }
 
-        return OpenApiValidationResult::failure($errors);
+        return OpenApiValidationResult::failure($errors, $matchedPath);
     }
 
     /**
@@ -186,6 +190,10 @@ private function normalizeMediaType(string $contentType): string
     }
 
     /**
+     * Check whether the given (already normalised, lower-cased) response content
+     * type matches any content type key defined in the spec. Spec keys are
+     * lower-cased before comparison.
+     *
      * @param array<string, array<string, mixed>> $content
      */
     private function isContentTypeInSpec(string $responseContentType, array $content): bool
@@ -199,6 +207,10 @@ private function isContentTypeInSpec(string $responseContentType, array $content
         return false;
     }
 
+    /**
+     * True for "application/json" or any "+json" structured syntax suffix (RFC 6838).
+     * Expects a lower-cased media type without parameters.
+     */
     private function isJsonContentType(string $lowerContentType): bool
     {
         return $lowerContentType === 'application/json' || str_ends_with($lowerContentType, '+json');

src/OpenApiValidationResult.php

@@ -23,9 +23,9 @@ public static function success(?string $matchedPath = null): self
     }
 
     /** @param string[] $errors */
-    public static function failure(array $errors): self
+    public static function failure(array $errors, ?string $matchedPath = null): self
     {
-        return new self(false, $errors);
+        return new self(false, $errors, $matchedPath);
     }
 
     public function isValid(): bool