test: prove OpenAPI 3.0 and 3.1 support, and fix the extension loss it found

.docs/README.md

@@ -1,10 +1,11 @@
 # Contributte OpenApi
 
-Pure PHP OpenAPI 3.0 implementation for Nette Framework.
+Pure PHP OpenAPI implementation for Nette Framework, supporting 3.0 and 3.1.
 
 ## Content
 
 - [Setup](#setup)
+- [Supported versions](#supported-versions)
 - [OpenAPI](#tracy)
 - [Version validation](#version-validation)
 - [Tracy](#tracy)
@@ -46,6 +47,21 @@ composer require contributte/openapi
 - [ServerVariable.php](../src/Schema/ServerVariable.php)
 - [Tag.php](../src/Schema/Tag.php)
 
+## Supported versions
+
+| OpenAPI | Support |
+|---------|---------|
+| 3.0     | yes     |
+| 3.1     | yes     |
+
+`tests/Cases/VersionSupportTest.php` backs both rows with a complete document per version -
+`tests/Cases/Schema/examples/complete-3-0.yaml` and `complete-3-1.yaml` - each using every field
+its version defines, except where the specification makes two fields mutually exclusive and only
+one of them can appear. For each document the test requires that a `fromArray()`/`toArray()` round
+trip loses nothing and that `VersionValidator` reports no problem. For the fields a version
+introduced, it additionally requires the document to exercise them, so a later version cannot be
+called supported while its additions go untested.
+
 ## Version validation
 
 The schema classes accept any document, whatever version it declares. `VersionValidator`

src/Schema/Header.php

@@ -29,6 +29,8 @@ class Header
 	/** @var MediaType[]|null */
 	private ?array $content = null;
 
+	private ?VendorExtensions $vendorExtensions = null;
+
 	/**
 	 * @param mixed[] $data
 	 */
@@ -62,6 +64,8 @@ public static function fromArray(array $data): Header
 			$header->setContent($key, MediaType::fromArray($contentData));
 		}
 
+		$header->setVendorExtensions(VendorExtensions::fromArray($data));
+
 		return $header;
 	}
 
@@ -116,6 +120,10 @@ public function toArray(): array
 			$data['content'] = array_map(static fn (MediaType $mediaType): array => $mediaType->toArray(), $this->content);
 		}
 
+		if ($this->vendorExtensions !== null) {
+			$data = array_merge($data, $this->vendorExtensions->toArray());
+		}
+
 		return $data;
 	}
 
@@ -177,4 +185,14 @@ public function setContent(string $type, MediaType $mediaType): void
 		$this->content[$type] = $mediaType;
 	}
 
+	public function getVendorExtensions(): ?VendorExtensions
+	{
+		return $this->vendorExtensions;
+	}
+
+	public function setVendorExtensions(?VendorExtensions $vendorExtensions): void
+	{
+		$this->vendorExtensions = $vendorExtensions;
+	}
+
 }

src/Schema/OAuthFlow.php

@@ -14,6 +14,8 @@ class OAuthFlow
 	/** @var array<string, string> */
 	private array $scopes;
 
+	private ?VendorExtensions $vendorExtensions = null;
+
 	/**
 	 * @param array<string, string> $scopes
 	 */
@@ -35,12 +37,15 @@ public function __construct(
 	 */
 	public static function fromArray(array $data): self
 	{
-		return new self(
+		$flow = new self(
 			$data['authorizationUrl'] ?? null,
 			$data['tokenUrl'] ?? null,
 			$data['refreshUrl'] ?? null,
 			$data['scopes'],
 		);
+		$flow->setVendorExtensions(VendorExtensions::fromArray($data));
+
+		return $flow;
 	}
 
 	/**
@@ -64,6 +69,10 @@ public function toArray(): array
 
 		$data['scopes'] = $this->scopes;
 
+		if ($this->vendorExtensions !== null) {
+			$data = array_merge($data, $this->vendorExtensions->toArray());
+		}
+
 		return $data;
 	}
 
@@ -113,4 +122,14 @@ public function setScopes(array $scopes): void
 		$this->scopes = $scopes;
 	}
 
+	public function getVendorExtensions(): ?VendorExtensions
+	{
+		return $this->vendorExtensions;
+	}
+
+	public function setVendorExtensions(?VendorExtensions $vendorExtensions): void
+	{
+		$this->vendorExtensions = $vendorExtensions;
+	}
+
 }

src/Schema/SecurityScheme.php

@@ -60,6 +60,8 @@ class SecurityScheme
 
 	private ?string $openIdConnectUrl = null;
 
+	private ?VendorExtensions $vendorExtensions = null;
+
 	public function __construct(string $type)
 	{
 		$this->setType($type);
@@ -79,6 +81,7 @@ public static function fromArray(array $data): SecurityScheme
 		$securityScheme->setBearerFormat($data['bearerFormat'] ?? null);
 		$securityScheme->setFlows(array_map(static fn (array $flow): OAuthFlow => OAuthFlow::fromArray($flow), $data['flows'] ?? []));
 		$securityScheme->setOpenIdConnectUrl($data['openIdConnectUrl'] ?? null);
+		$securityScheme->setVendorExtensions(VendorExtensions::fromArray($data));
 
 		return $securityScheme;
 	}
@@ -119,6 +122,10 @@ public function toArray(): array
 			$data['openIdConnectUrl'] = $this->openIdConnectUrl;
 		}
 
+		if ($this->vendorExtensions !== null) {
+			$data = array_merge($data, $this->vendorExtensions->toArray());
+		}
+
 		return $data;
 	}
 
@@ -260,6 +267,16 @@ public function setOpenIdConnectUrl(?string $openIdConnectUrl): void
 		$this->openIdConnectUrl = $openIdConnectUrl;
 	}
 
+	public function getVendorExtensions(): ?VendorExtensions
+	{
+		return $this->vendorExtensions;
+	}
+
+	public function setVendorExtensions(?VendorExtensions $vendorExtensions): void
+	{
+		$this->vendorExtensions = $vendorExtensions;
+	}
+
 	private static function validateFlow(string $flowType, OAuthFlow $flow): void
 	{
 		$needsAuthorizationUrl = in_array($flowType, [

src/Validator/VersionValidator.php

@@ -22,7 +22,7 @@ class VersionValidator
 	 * Fields and the version that introduced them. A "*" segment matches any key
 	 * of a map.
 	 */
-	private const FIELD_INTRODUCED_IN = [
+	public const FIELD_INTRODUCED_IN = [
 		'jsonSchemaDialect' => Version::V3_1,
 		'webhooks' => Version::V3_1,
 		'info.summary' => Version::V3_1,
@@ -34,7 +34,7 @@ class VersionValidator
 	 * Field values and the version that introduced them, as
 	 * "document path => [value => version]".
 	 */
-	private const VALUE_INTRODUCED_IN = [
+	public const VALUE_INTRODUCED_IN = [
 		'components.securitySchemes.*.type' => [
 			SecurityScheme::TYPE_MUTUAL_TLS => Version::V3_1,
 		],

tests/Cases/Schema/HeaderTest.php

@@ -33,6 +33,19 @@ public function testContent(): void
 		Assert::same($expectedData, Header::fromArray($expectedData)->toArray());
 	}
 
+	public function testVendorExtensions(): void
+	{
+		$expectedData = [
+			'description' => 'The number of allowed requests in the current period',
+			'x-internal' => true,
+		];
+
+		$header = Header::fromArray($expectedData);
+
+		Assert::same(true, $header->getVendorExtensions()?->getExtension('x-internal'));
+		Assert::same($expectedData, $header->toArray());
+	}
+
 }
 
 (new HeaderTest())->run();

tests/Cases/Schema/OAuthFlowTest.php

@@ -65,6 +65,20 @@ public function testClientCredentialsFlowWithoutAuthorizationUrl(): void
 		Assert::same($data, $flow->toArray());
 	}
 
+	public function testVendorExtensions(): void
+	{
+		$expectedData = [
+			'authorizationUrl' => 'https://example.com/authorization',
+			'scopes' => ['read' => 'Read access'],
+			'x-internal' => true,
+		];
+
+		$flow = OAuthFlow::fromArray($expectedData);
+
+		Assert::same(true, $flow->getVendorExtensions()?->getExtension('x-internal'));
+		Assert::same($expectedData, $flow->toArray());
+	}
+
 	/**
 	 * The OpenAPI Specification marks `scopes` as REQUIRED on the OAuth Flow Object (the map MAY
 	 * be empty, but the key MUST be present). fromArray() must not silently manufacture it - a

tests/Cases/Schema/SecuritySchemeTest.php

@@ -116,6 +116,21 @@ public function testOptional(): void
 		Assert::same($expected, SecurityScheme::fromArray($array)->toArray());
 	}
 
+	public function testVendorExtensions(): void
+	{
+		$expectedData = [
+			'type' => SecurityScheme::TYPE_API_KEY,
+			'name' => 'api_key',
+			'in' => SecurityScheme::IN_HEADER,
+			'x-internal' => true,
+		];
+
+		$securityScheme = SecurityScheme::fromArray($expectedData);
+
+		Assert::same(true, $securityScheme->getVendorExtensions()?->getExtension('x-internal'));
+		Assert::same($expectedData, $securityScheme->toArray());
+	}
+
 	public function testInvalidType(): void
 	{
 		Assert::exception(static function (): void {