Flesh out and hook up migration guide for v6

Author: DerManoMann

docs/.vitepress/config.js

@@ -24,6 +24,7 @@ function getGuideSidebar() {
     {
       text: 'Upgrading',
       items: [
+        { text: 'Migration from 5.x to 6.x', link: '/guide/migrating-to-v6' },
         { text: 'Migration from 4.x to 5.x', link: '/guide/migrating-to-v5' },
         { text: 'Migration from 3.x to 4.x', link: '/guide/migrating-to-v4' },
         { text: 'Migration from 2.x to 3.x', link: '/guide/migrating-to-v3' },

docs/guide/migrating-to-v6.md

@@ -2,13 +2,33 @@
 
 ## Overview
 
-v6 is mostly a cleanup release with updated dependencies. The main changes are:
+`v6` is mostly a cleanup release, with updated dependencies. The main changes are:
 
-* Minimum required PHP version is now 8.2
-* ...
+* The minimum required PHP version is now 8.2
+* `radebatz/type-info-extras` is now a required dependency
+* `TypeInfoTypeResolver` now properly handles composite types (unions and intersections)
+* Some deprecations have been removed (see below)
+* The `MediaType::encoding` property now only accepts `Encoding` objects (BC break)
 
 For most installations upgrading should not require any changes.
 
+## Type resolvers
+With `radebatz/type-info-extras` now being a required dependency, the `TypeInfoTypeResolver` is not the de-facto default
+resolver.
+
+The `LegacyTypeResolver` can still be used as a drop-in replacement, but is now marked `deprecated` and will be removed
+in v7.
+
 ## Removed deprecated elements
-### `\Openapi\Generator::getProcessors()` and `\Openapi\Generator::setProcessors()`
+### Methods `\Openapi\Generator::getProcessors()` and `\Openapi\Generator::setProcessors()`
 Use `getProcessorPipeline()` and `setProcessorPipeline(new Pipeline(...))` methods instead
+
+### Static method `\Openapi\Generator::scan()`
+Main entry point into the `Generator` is now the **non-static** `generate()` method:
+```php
+(new Generator())->generate(/* ... */);
+```
+
+### `Utils` helper
+Most methods in the class were internal to start with and the `Util::finder()` factory methods is now replaced with
+the new `SourceFinder` class.

src/Annotations/AbstractAnnotation.php

@@ -366,7 +366,7 @@ public function jsonSerialize()
             if (isset($data->type) && is_array($data->type)) {
                 if (in_array('null', $data->type)) {
                     $data->nullable = true;
-                    $data->type = array_filter($data->type, fn ($t): bool => 'null' !== $t);
+                    $data->type = array_filter($data->type, fn ($v): bool => $v !== 'null');
                     if (1 === count($data->type)) {
                         $data->type = array_pop($data->type);
                     }

src/Annotations/MediaType.php

@@ -11,6 +11,8 @@
 /**
  * Each Media Type object provides schema and examples for the media type identified by its key.
  *
+ * Parameter encodings can be set either here, or on nested `Property` annotations directly.
+ *
  * @see [Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object)
  *
  * @Annotation

src/Type/LegacyTypeResolver.php

@@ -12,6 +12,9 @@
 use OpenApi\Generator;
 use OpenApi\TypeResolverInterface;
 
+/**
+ * @deprecated use `TypeInfoTypeResolver` instead
+ */
 class LegacyTypeResolver extends AbstractTypeResolver
 {
     /** @inheritdoc */