feat(validator): accept response Content-Type for content negotiation

Add optional $responseContentType parameter to OpenApiResponseValidator::validate().
When provided, non-JSON content types defined in the spec are skipped (success),
undefined types produce a failure, and JSON-compatible types proceed to schema validation.

Move the Content-Type mismatch logic from ValidatesOpenApiSchema trait into the
validator itself for a single source of truth.

Closes #22

Author: wadakatu

src/Laravel/ValidatesOpenApiSchema.php

@@ -50,7 +50,6 @@ protected function assertResponseMatchesOpenApiSchema(
         }
 
         $contentType = $response->headers->get('Content-Type', '');
-        $hasNonJsonContentType = $content !== '' && $contentType !== '' && !str_contains(strtolower($contentType), 'json');
 
         $validator = new OpenApiResponseValidator();
         $result = $validator->validate(
@@ -59,6 +58,7 @@ protected function assertResponseMatchesOpenApiSchema(
             $resolvedPath,
             $response->getStatusCode(),
             $this->extractJsonBody($response, $content, $contentType),
+            $contentType !== '' ? $contentType : null,
         );
 
         // Record coverage for any matched endpoint, including those where body
@@ -72,17 +72,6 @@ protected function assertResponseMatchesOpenApiSchema(
             );
         }
 
-        // This guard catches the case where the spec defines a JSON content type
-        // but the actual response has a non-JSON Content-Type header. The validator
-        // itself skips validation for specs that define *only* non-JSON content
-        // types (returning success), so this guard only fires for the mismatch case.
-        if (!$result->isValid() && $hasNonJsonContentType) {
-            $this->fail(
-                "OpenAPI schema validation failed for {$resolvedMethod} {$resolvedPath} (spec: {$specName}):\n"
-                . "Response has Content-Type '{$contentType}' but the spec expects a JSON response.",
-            );
-        }
-
         $this->assertTrue(
             $result->isValid(),
             "OpenAPI schema validation failed for {$resolvedMethod} {$resolvedPath} (spec: {$specName}):\n"

src/OpenApiResponseValidator.php

@@ -10,10 +10,13 @@
 use Opis\JsonSchema\Validator;
 
 use function array_keys;
+use function implode;
 use function json_decode;
 use function json_encode;
 use function str_ends_with;
+use function strstr;
 use function strtolower;
+use function trim;
 
 final class OpenApiResponseValidator
 {
@@ -23,6 +26,7 @@ public function validate(
         string $requestPath,
         int $statusCode,
         mixed $responseBody,
+        ?string $responseContentType = null,
     ): OpenApiValidationResult {
         $spec = OpenApiSpecLoader::load($specName);
 
@@ -66,6 +70,28 @@ 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).
+        if ($responseContentType !== null) {
+            $normalizedType = $this->normalizeMediaType($responseContentType);
+
+            if (!$this->isJsonContentType($normalizedType)) {
+                // Non-JSON response: check if the content type is defined in the spec.
+                if ($this->isContentTypeInSpec($normalizedType, $content)) {
+                    return OpenApiValidationResult::success($matchedPath);
+                }
+
+                $defined = implode(', ', array_keys($content));
+
+                return OpenApiValidationResult::failure([
+                    "Response Content-Type '{$normalizedType}' is not defined for {$method} {$matchedPath} (status {$statusCode}) in '{$specName}' spec. Defined content types: {$defined}",
+                ]);
+            }
+
+            // JSON-compatible response: fall through to existing JSON schema validation.
+        }
+
         $jsonContentType = $this->findJsonContentType($content);
 
         // If no JSON-compatible content type is defined, skip body validation.
@@ -138,11 +164,43 @@ private function findJsonContentType(array $content): ?string
         foreach ($content as $contentType => $mediaType) {
             $lower = strtolower($contentType);
 
-            if ($lower === 'application/json' || str_ends_with($lower, '+json')) {
+            if ($this->isJsonContentType($lower)) {
                 return $contentType;
             }
         }
 
         return null;
     }
+
+    /**
+     * Extract the media type portion before any parameters (e.g. charset),
+     * and return it lower-cased.
+     *
+     * Example: "text/html; charset=utf-8" → "text/html"
+     */
+    private function normalizeMediaType(string $contentType): string
+    {
+        $mediaType = strstr($contentType, ';', true);
+
+        return strtolower(trim($mediaType !== false ? $mediaType : $contentType));
+    }
+
+    /**
+     * @param array<string, array<string, mixed>> $content
+     */
+    private function isContentTypeInSpec(string $responseContentType, array $content): bool
+    {
+        foreach ($content as $specContentType => $mediaType) {
+            if (strtolower($specContentType) === $responseContentType) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private function isJsonContentType(string $lowerContentType): bool
+    {
+        return $lowerContentType === 'application/json' || str_ends_with($lowerContentType, '+json');
+    }
 }