Improve exceptions message (#1502)

Controller/DocumentationController.php

@@ -44,7 +44,7 @@ final class DocumentationController
     public function __invoke(Request $request, $area = 'default')
     {
         if (!$this->generatorLocator->has($area)) {
-            throw new BadRequestHttpException(sprintf('Area "%s" is not supported.', $area));
+            throw new BadRequestHttpException(sprintf('Area "%s" is not supported as it isn\'t defined in config.', $area));
         }
 
         $spec = $this->generatorLocator->get($area)->generate()->toArray();

Controller/SwaggerUiController.php

@@ -47,7 +47,12 @@ final class SwaggerUiController
     public function __invoke(Request $request, $area = 'default')
     {
         if (!$this->generatorLocator->has($area)) {
-            throw new BadRequestHttpException(sprintf('Area "%s" is not supported.', $area));
+            $advice = '';
+            if (false !== strpos($area, '.json')) {
+                $advice = ' Since the area provided contains `.json`, the issue is likely caused by route priorities. Try switching the Swagger UI / the json documentation routes order.';
+            }
+
+            throw new BadRequestHttpException(sprintf('Area "%s" is not supported as it isn\'t defined in config.%s', $area, $advice));
         }
 
         $spec = $this->generatorLocator->get($area)->generate()->toArray();

Describer/ApiPlatformDescriber.php

@@ -19,7 +19,7 @@ final class ApiPlatformDescriber extends ExternalDocDescriber
     public function __construct(Documentation $documentation, NormalizerInterface $normalizer)
     {
         if (!$normalizer->supportsNormalization($documentation, 'json')) {
-            throw new \InvalidArgumentException(sprintf('Argument 2 passed to %s() must implement %s and support normalization of %s, %s given.', __METHOD__, NormalizerInterface::class, Documentation::class, get_class($normalizer)));
+            throw new \InvalidArgumentException(sprintf('Argument 2 passed to %s() must implement %s and support normalization of %s. The normalizer provided is an instance of %s.', __METHOD__, NormalizerInterface::class, Documentation::class, get_class($normalizer)));
         }
 
         parent::__construct(function () use ($documentation, $normalizer) {

Describer/SwaggerPhpDescriber.php

@@ -181,7 +181,7 @@ final class SwaggerPhpDescriber implements ModelRegistryAwareInterface
                 }
 
                 if (!$annotation instanceof SWG\Response && !$annotation instanceof SWG\Parameter && !$annotation instanceof SWG\ExternalDocumentation) {
-                    throw new \LogicException(sprintf('Using the annotation "%s" as a root annotation in "%s::%s()" is not allowed.', get_class($annotation), $method->getDeclaringClass()->name, $method->name));
+                    throw new \LogicException(sprintf('Using the annotation "%s" as a root annotation in "%s::%s()" is not allowed. It should probably be nested in a `@SWG\Response` or `@SWG\Parameter` annotation.', get_class($annotation), $method->getDeclaringClass()->name, $method->name));
                 }
 
                 $implicitAnnotations[] = $annotation;

ModelDescriber/ObjectModelDescriber.php

@@ -79,17 +79,17 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
 
             $types = $this->propertyInfo->getTypes($class, $propertyName);
             if (null === $types || 0 === count($types)) {
-                throw new \LogicException(sprintf('The PropertyInfo component was not able to guess the type of %s::$%s', $class, $propertyName));
+                throw new \LogicException(sprintf('The PropertyInfo component was not able to guess the type of %s::$%s. You may need to add a `@var` annotation or use `@SWG\Property(type="")` to make its type explicit.', $class, $propertyName));
             }
             if (count($types) > 1) {
-                throw new \LogicException(sprintf('Property %s::$%s defines more than one type.', $class, $propertyName));
+                throw new \LogicException(sprintf('Property %s::$%s defines more than one type. You can specify the one that should be documented using `@SWG\Property(type="")`.', $class, $propertyName));
             }
 
             $type = $types[0];
             if ($type->isCollection()) {
                 $type = $type->getCollectionValueType();
                 if (null === $type) {
-                    throw new \LogicException(sprintf('Property "%s:%s" is an array, but no indication of the array elements are made. Use e.g. string[] for an array of string.', $class, $propertyName));
+                    throw new \LogicException(sprintf('Property "%s:%s" is an array, but its items type isn\'t specified. You can specify that by using the type `string[]` for instance or `@SWG\Property(type="array", @SWG\Items(type="string"))`.', $class, $propertyName));
                 }
 
                 $property->setType('array');