refactor: move OpenApiSpec attribute to core namespace for framework-agnostic use

Extract OpenApiSpec attribute from Laravel namespace to
Studio\OpenApiContractTesting and introduce OpenApiSpecResolver trait
with an openApiSpecFallback() hook. The Laravel trait now composes
OpenApiSpecResolver and overrides the fallback for config-based defaults.

Author: wadakatu

README.md

@@ -109,7 +109,7 @@ class GetPetsTest extends TestCase
 To use a different spec for a specific test class, add the `#[OpenApiSpec]` attribute:
 
 ```php
-use Studio\OpenApiContractTesting\Laravel\OpenApiSpec;
+use Studio\OpenApiContractTesting\OpenApiSpec;
 use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
 
 #[OpenApiSpec('admin')]
@@ -153,6 +153,38 @@ Resolution priority (highest to lowest):
 
 #### Framework-agnostic
 
+You can use the `#[OpenApiSpec]` attribute with the `OpenApiSpecResolver` trait in any PHPUnit test:
+
+```php
+use Studio\OpenApiContractTesting\OpenApiSpec;
+use Studio\OpenApiContractTesting\OpenApiSpecResolver;
+use Studio\OpenApiContractTesting\OpenApiResponseValidator;
+
+#[OpenApiSpec('front')]
+class GetPetsTest extends TestCase
+{
+    use OpenApiSpecResolver;
+
+    public function test_list_pets(): void
+    {
+        $specName = $this->resolveOpenApiSpec(); // 'front'
+        $validator = new OpenApiResponseValidator();
+        $result = $validator->validate(
+            specName: $specName,
+            method: 'GET',
+            requestPath: '/api/v1/pets',
+            statusCode: 200,
+            responseBody: $decodedJsonBody,
+            responseContentType: 'application/json',
+        );
+
+        $this->assertTrue($result->isValid(), $result->errorMessage());
+    }
+}
+```
+
+Or without the attribute, pass the spec name directly:
+
 ```php
 use Studio\OpenApiContractTesting\OpenApiResponseValidator;
 use Studio\OpenApiContractTesting\OpenApiSpecLoader;

src/Laravel/ValidatesOpenApiSchema.php

@@ -6,11 +6,10 @@
 
 use Illuminate\Testing\TestResponse;
 use JsonException;
-use ReflectionClass;
-use ReflectionMethod;
 use Studio\OpenApiContractTesting\HttpMethod;
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
 use Studio\OpenApiContractTesting\OpenApiResponseValidator;
+use Studio\OpenApiContractTesting\OpenApiSpecResolver;
 
 use function is_numeric;
 use function is_string;
@@ -19,6 +18,8 @@
 
 trait ValidatesOpenApiSchema
 {
+    use OpenApiSpecResolver;
+
     protected function openApiSpec(): string
     {
         $spec = config('openapi-contract-testing.default_spec');
@@ -30,6 +31,11 @@ protected function openApiSpec(): string
         return $spec;
     }
 
+    protected function openApiSpecFallback(): string
+    {
+        return $this->openApiSpec();
+    }
+
     protected function assertResponseMatchesOpenApiSchema(
         TestResponse $response,
         ?HttpMethod $method = null,
@@ -86,27 +92,6 @@ protected function assertResponseMatchesOpenApiSchema(
         );
     }
 
-    private function resolveOpenApiSpec(): string
-    {
-        // 1. Method-level #[OpenApiSpec] attribute
-        $methodName = $this->name(); // @phpstan-ignore method.notFound
-        $refMethod = new ReflectionMethod($this, $methodName);
-        $methodAttrs = $refMethod->getAttributes(OpenApiSpec::class);
-        if ($methodAttrs !== []) {
-            return $methodAttrs[0]->newInstance()->name;
-        }
-
-        // 2. Class-level #[OpenApiSpec] attribute
-        $refClass = new ReflectionClass($this);
-        $classAttrs = $refClass->getAttributes(OpenApiSpec::class);
-        if ($classAttrs !== []) {
-            return $classAttrs[0]->newInstance()->name;
-        }
-
-        // 3. openApiSpec() method override / config default
-        return $this->openApiSpec();
-    }
-
     /** @return null|array<string, mixed> */
     private function extractJsonBody(TestResponse $response, string $content, string $contentType): ?array
     {

src/Laravel/OpenApiSpec.php src/OpenApiSpec.phpsrc/Laravel/OpenApiSpec.php renamed to src/OpenApiSpec.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Studio\OpenApiContractTesting\Laravel;
+namespace Studio\OpenApiContractTesting;
 
 use Attribute;
 

src/OpenApiSpecResolver.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Studio\OpenApiContractTesting;
+
+use ReflectionClass;
+use ReflectionMethod;
+
+trait OpenApiSpecResolver
+{
+    protected function openApiSpecFallback(): string
+    {
+        return '';
+    }
+
+    private function resolveOpenApiSpec(): string
+    {
+        // 1. Method-level #[OpenApiSpec] attribute
+        $methodName = $this->name(); // @phpstan-ignore method.notFound
+        $refMethod = new ReflectionMethod($this, $methodName);
+        $methodAttrs = $refMethod->getAttributes(OpenApiSpec::class);
+        if ($methodAttrs !== []) {
+            return $methodAttrs[0]->newInstance()->name;
+        }
+
+        // 2. Class-level #[OpenApiSpec] attribute
+        $refClass = new ReflectionClass($this);
+        $classAttrs = $refClass->getAttributes(OpenApiSpec::class);
+        if ($classAttrs !== []) {
+            return $classAttrs[0]->newInstance()->name;
+        }
+
+        // 3. Subclass hook (e.g. openApiSpec() in Laravel trait)
+        return $this->openApiSpecFallback();
+    }
+}

tests/Unit/OpenApiSpecResolverFallbackTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Studio\OpenApiContractTesting\Tests\Unit;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Studio\OpenApiContractTesting\OpenApiSpecResolver;
+
+class OpenApiSpecResolverFallbackTest extends TestCase
+{
+    use OpenApiSpecResolver;
+
+    #[Test]
+    public function fallback_is_used_when_no_attribute_present(): void
+    {
+        $this->assertSame('from-fallback', $this->resolveOpenApiSpec());
+    }
+
+    protected function openApiSpecFallback(): string
+    {
+        return 'from-fallback';
+    }
+}

tests/Unit/OpenApiSpecResolverTest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Studio\OpenApiContractTesting\Tests\Unit;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Studio\OpenApiContractTesting\OpenApiSpec;
+use Studio\OpenApiContractTesting\OpenApiSpecResolver;
+
+#[OpenApiSpec('petstore-3.0')]
+class OpenApiSpecResolverTest extends TestCase
+{
+    use OpenApiSpecResolver;
+
+    #[Test]
+    public function class_level_attribute_is_resolved(): void
+    {
+        $this->assertSame('petstore-3.0', $this->resolveOpenApiSpec());
+    }
+
+    #[Test]
+    #[OpenApiSpec('petstore-3.1')]
+    public function method_level_attribute_overrides_class_level(): void
+    {
+        $this->assertSame('petstore-3.1', $this->resolveOpenApiSpec());
+    }
+
+    #[Test]
+    public function fallback_returns_empty_string_when_no_attribute(): void
+    {
+        // This test class has a class-level attribute, so we verify
+        // the fallback method itself returns empty by default.
+        $this->assertSame('', $this->openApiSpecFallback());
+    }
+}

tests/Unit/ValidatesOpenApiSchemaAttributeTest.php

@@ -9,9 +9,9 @@
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use Studio\OpenApiContractTesting\HttpMethod;
-use Studio\OpenApiContractTesting\Laravel\OpenApiSpec;
 use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
+use Studio\OpenApiContractTesting\OpenApiSpec;
 use Studio\OpenApiContractTesting\OpenApiSpecLoader;
 use Studio\OpenApiContractTesting\Tests\Helpers\CreatesTestResponse;