Add OpenAPI 3.1 support and schema enhancements

README.md

@@ -8,14 +8,35 @@
 [![GitHub release](https://img.shields.io/github/release/byjg/php-swagger-test.svg)](https://github.com/byjg/php-swagger-test/releases/)
 
 A set of tools for testing your REST calls based on the OpenApi specification using PHPUnit.
-Currently, this library supports the OpenApi specifications `2.0` (formerly swagger) and `3.0`.
+Currently, this library supports the OpenApi specifications `2.0` (formerly swagger), `3.0.x`, and **`3.1.x`**.
+
+## OpenAPI Version Support
+
+- **Swagger 2.0** - Full support
+- **OpenAPI 3.0.x** - Full support (3.0.0, 3.0.1, 3.0.2, 3.0.3)
+- **OpenAPI 3.1.x** - Full support with JSON Schema 2020-12 features ✨
+
+### OpenAPI 3.1 Features
+
+OpenAPI 3.1 brings full JSON Schema 2020-12 compatibility. Key features supported:
+
+- **Nullable Types**: Use JSON Schema union types `["string", "null"]` instead of the deprecated `nullable` keyword
+- **Webhooks**: Describe and validate incoming HTTP requests your API will receive
+- **`const` Keyword**: Validate constant values
+- **Conditional Schemas**: Use `if/then/else` for conditional validation
+- **Tuple Validation**: Validate arrays with specific types at specific positions using `prefixItems`
+- **`$ref` with Sibling Keywords**: References can have additional properties alongside them
+
+For detailed documentation on OpenAPI 3.1 features, see [OpenAPI 3.1 Features Guide](docs/openapi-3.1-features.md).
+
+### Limitations
 
 Some features of the OpenAPI specification are not fully implemented:
 
-- Callbacks (OpenAPI 3.0)
-- Links (OpenAPI 3.0)
+- Callbacks (OpenAPI 3.0/3.1)
+- Links (OpenAPI 3.0/3.1)
 - References to external documents/objects
-- Complex schema validations
+- Some advanced JSON Schema 2020-12 keywords (e.g., `unevaluatedProperties`, `dependentSchemas`)
 
 For details on the schema classes and their specific features, see [Schema Classes](docs/schema-classes.md).
 
@@ -34,12 +55,14 @@ The ApiTestCase's assertion process is based on throwing exceptions if some vali
 - [Contract test cases](docs/contract-tests.md) - Testing without HTTP using custom requesters
 - [Runtime parameters validator](docs/runtime-parameters-validator.md) - Validating requests in production
 - [Mocking Requests](docs/mock-requests.md) - Testing with mocked responses
-- [Schema classes](docs/schema-classes.md) - Working with OpenAPI 2.0 and 3.0 schemas
+- [Schema classes](docs/schema-classes.md) - Working with OpenAPI 2.0, 3.0, and 3.1 schemas
+- [OpenAPI 3.1 features](docs/openapi-3.1-features.md) - Webhooks, const, if/then/else, tuple validation, and more
 - [Using the OpenApiValidation trait](docs/trait-usage.md) - Flexible validation without extending ApiTestCase
 - [Advanced usage](docs/advanced-usage.md) - File uploads, custom clients, authentication, and more
 - [Exception handling](docs/exceptions.md) - Understanding and handling validation exceptions
 - [Migration guide](docs/migration-guide.md) - Upgrading from older versions
 - [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+- [Version comparison](docs/version-comparison.md) - Feature support matrix across OpenAPI versions
 
 ## Who is using this library?
 

docs/advanced-usage.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Advanced Usage

docs/exceptions.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Exception Handling
@@ -543,17 +543,17 @@ class ApiController
 
 ## Exception Quick Reference
 
-| Exception | When Thrown | HTTP Status Hint |
-|-----------|-------------|------------------|
-| `PathNotFoundException` | Path not in spec | 404 (likely) |
-| `HttpMethodNotFoundException` | Method not allowed for path | 405 (likely) |
-| `DefinitionNotFoundException` | Schema reference not found | 500 (spec error) |
-| `InvalidDefinitionException` | Spec structure invalid | 500 (spec error) |
-| `NotMatchedException` | Data doesn't match schema | 400 (validation) |
-| `RequiredArgumentNotFound` | Missing required field | 400 (validation) |
-| `StatusCodeNotMatchedException` | Wrong status code | N/A |
-| `InvalidRequestException` | Malformed request | 400 (client error) |
-| `GenericApiException` | General API error | Varies |
+| Exception                       | When Thrown                 | HTTP Status Hint   |
+|---------------------------------|-----------------------------|--------------------|
+| `PathNotFoundException`         | Path not in spec            | 404 (likely)       |
+| `HttpMethodNotFoundException`   | Method not allowed for path | 405 (likely)       |
+| `DefinitionNotFoundException`   | Schema reference not found  | 500 (spec error)   |
+| `InvalidDefinitionException`    | Spec structure invalid      | 500 (spec error)   |
+| `NotMatchedException`           | Data doesn't match schema   | 400 (validation)   |
+| `RequiredArgumentNotFound`      | Missing required field      | 400 (validation)   |
+| `StatusCodeNotMatchedException` | Wrong status code           | N/A                |
+| `InvalidRequestException`       | Malformed request           | 400 (client error) |
+| `GenericApiException`           | General API error           | Varies             |
 
 ---