From 258dd2f69f9b2c6c06a282161b04a117e26e6c06 Mon Sep 17 00:00:00 2001 From: Guilhem N Date: Fri, 12 Apr 2019 09:35:49 +0200 Subject: [PATCH] Improve exceptions message (#1502) --- Controller/DocumentationController.php | 2 +- Controller/SwaggerUiController.php | 7 ++++++- Describer/ApiPlatformDescriber.php | 2 +- Describer/SwaggerPhpDescriber.php | 2 +- ModelDescriber/ObjectModelDescriber.php | 6 +++--- 5 files changed, 12 insertions(+), 7 deletions(-) diff --git a/Controller/DocumentationController.php b/Controller/DocumentationController.php index 453c2e2..2a9ed3c 100644 --- a/Controller/DocumentationController.php +++ b/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(); diff --git a/Controller/SwaggerUiController.php b/Controller/SwaggerUiController.php index a8ccca3..a80f013 100644 --- a/Controller/SwaggerUiController.php +++ b/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(); diff --git a/Describer/ApiPlatformDescriber.php b/Describer/ApiPlatformDescriber.php index 0c28b29..70d2cc3 100644 --- a/Describer/ApiPlatformDescriber.php +++ b/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) { diff --git a/Describer/SwaggerPhpDescriber.php b/Describer/SwaggerPhpDescriber.php index b6327df..956bc53 100644 --- a/Describer/SwaggerPhpDescriber.php +++ b/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; diff --git a/ModelDescriber/ObjectModelDescriber.php b/ModelDescriber/ObjectModelDescriber.php index 552cca9..388d490 100644 --- a/ModelDescriber/ObjectModelDescriber.php +++ b/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');