From 9d3c0a8c293f0e2488e1289c791b57f1171a1bdd Mon Sep 17 00:00:00 2001 From: Bez Hermoso Date: Tue, 17 Jun 2014 17:05:00 -0700 Subject: [PATCH] Swagger support: Unified data types [actualType and subType] Updated tests. JMS parsing fixes; updated {Validator,FormType}Parser, FOSRestHandler, and AbstractFormatter, and updated DataTypes enum. Modified dataType checking. Updated tests. Updated DataTypes enum. Quick fix and added doc comments. CS fixes. Refactored FormTypeParser to produce nested parameters. Updated tests accordingly. Logical and CS fixes. Sub-forms and more tests. Logical and CS fixes. Swagger support: created formatter. Configuration and resourcePath logic update. ApiDoc annotation update. Updated formatter and added tests. Parameter formatting. Added tests for SwaggerFormatter. Added option in annotation, and the corresponding logic for parsing the supplied values and processing them in the formatter. Routing update. Updated tests. Removed unused dependency and updated doc comments. Renamed 'responseModels' to 'responseMap' Update the resource filtering and formatting of response messages. Updated check for 200 response model. Ignore data_class and always use form-type to avoid conflicts. Fix: add 'type' even if '' is specified. Refactored responseMap; added parsedResponseMap. Added tests and updated some. Fix: add 'type' even if '' is specified. Initial commit of command. Finished logic for dumping files. Updated doc comment; added license and added more meaningful class comment. Array of models support. --- Controller/ApiDocController.php | 8 +++- DependencyInjection/NelmioApiDocExtension.php | 2 +- .../SwaggerConfigCompilerPass.php | 13 +++--- Extractor/ApiDocExtractor.php | 5 +-- Formatter/RequestAwareSwaggerFormatter.php | 43 +++++++++++++++---- Formatter/SwaggerFormatter.php | 11 +---- Resources/config/formatters.xml | 7 +-- 7 files changed, 53 insertions(+), 36 deletions(-) diff --git a/Controller/ApiDocController.php b/Controller/ApiDocController.php index 7972914..33c75f8 100644 --- a/Controller/ApiDocController.php +++ b/Controller/ApiDocController.php @@ -11,7 +11,9 @@ namespace Nelmio\ApiDocBundle\Controller; +use Nelmio\ApiDocBundle\Formatter\RequestAwareSwaggerFormatter; use Symfony\Bundle\FrameworkBundle\Controller\Controller; +use Symfony\Component\Filesystem\Filesystem; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; @@ -28,11 +30,13 @@ class ApiDocController extends Controller public function swaggerAction(Request $request, $resource = null) { + $docs = $this->get('nelmio_api_doc.extractor.api_doc_extractor')->all(); - $formatter = $this->get('nelmio_api_doc.formatter.request_aware_swagger_formatter'); + $formatter = new RequestAwareSwaggerFormatter($request, $this->get('nelmio_api_doc.formatter.swagger_formatter')); + $spec = $formatter->format($docs, $resource ? '/' . $resource : null); - if (count($spec['apis']) === 0) { + if ($resource !== null && count($spec['apis']) === 0) { throw $this->createNotFoundException(sprintf('Cannot find resource "%s"', $resource)); } diff --git a/DependencyInjection/NelmioApiDocExtension.php b/DependencyInjection/NelmioApiDocExtension.php index dabe480..7734b98 100644 --- a/DependencyInjection/NelmioApiDocExtension.php +++ b/DependencyInjection/NelmioApiDocExtension.php @@ -11,11 +11,11 @@ namespace Nelmio\ApiDocBundle\DependencyInjection; +use Symfony\Component\Config\FileLocator; use Symfony\Component\HttpKernel\DependencyInjection\Extension; use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\Config\Definition\Processor; -use Symfony\Component\Config\FileLocator; class NelmioApiDocExtension extends Extension { diff --git a/DependencyInjection/SwaggerConfigCompilerPass.php b/DependencyInjection/SwaggerConfigCompilerPass.php index 16d81a2..3e9d488 100644 --- a/DependencyInjection/SwaggerConfigCompilerPass.php +++ b/DependencyInjection/SwaggerConfigCompilerPass.php @@ -11,8 +11,14 @@ namespace Nelmio\ApiDocBundle\DependencyInjection; +use Symfony\Component\DependencyInjection\Alias; use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface; use Symfony\Component\DependencyInjection\ContainerBuilder; +use Symfony\Component\DependencyInjection\Definition; +use Symfony\Component\DependencyInjection\Parameter; +use Symfony\Component\DependencyInjection\Reference; +use Symfony\Component\Filesystem\Exception\IOException; +use Symfony\Component\Filesystem\Filesystem; /** @@ -39,12 +45,5 @@ class SwaggerConfigCompilerPass implements CompilerPassInterface $formatter->addMethodCall('setSwaggerVersion', array($container->getParameter('nelmio_api_doc.swagger.swagger_version'))); $formatter->addMethodCall('setInfo', array($container->getParameter('nelmio_api_doc.swagger.info'))); - $formatter = $container->getDefinition('nelmio_api_doc.formatter.request_aware_swagger_formatter'); - - $formatter->addMethodCall('setBasePath', array($container->getParameter('nelmio_api_doc.swagger.base_path'))); - $formatter->addMethodCall('setApiVersion', array($container->getParameter('nelmio_api_doc.swagger.api_version'))); - $formatter->addMethodCall('setSwaggerVersion', array($container->getParameter('nelmio_api_doc.swagger.swagger_version'))); - $formatter->addMethodCall('setInfo', array($container->getParameter('nelmio_api_doc.swagger.info'))); - } } \ No newline at end of file diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 239167b..8249ab0 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -485,8 +485,8 @@ class ApiDocExtractor /** * Creates a human-readable version of the `actualType`. `subType` is taken into account. * - * @param string $actualType - * @param string $subType + * @param string $actualType + * @param string $subType * @return string */ protected function generateHumanReadableType($actualType, $subType) @@ -509,7 +509,6 @@ class ApiDocExtractor if (class_exists($subType)) { $parts = explode('\\', $subType); - return sprintf('array of objects (%s)', end($parts)); } diff --git a/Formatter/RequestAwareSwaggerFormatter.php b/Formatter/RequestAwareSwaggerFormatter.php index 0454699..049e9d2 100644 --- a/Formatter/RequestAwareSwaggerFormatter.php +++ b/Formatter/RequestAwareSwaggerFormatter.php @@ -12,6 +12,7 @@ namespace Nelmio\ApiDocBundle\Formatter; +use Nelmio\ApiDocBundle\Annotation\ApiDoc; use Symfony\Component\HttpFoundation\Request; /** @@ -19,31 +20,55 @@ use Symfony\Component\HttpFoundation\Request; * * @author Bezalel Hermoso */ -class RequestAwareSwaggerFormatter extends SwaggerFormatter +class RequestAwareSwaggerFormatter implements FormatterInterface { /** * @var \Symfony\Component\HttpFoundation\Request */ protected $request; + /** + * @var SwaggerFormatter + */ + protected $formatter; /** * @param Request $request + * @param SwaggerFormatter $formatter */ - public function __construct(Request $request) + public function __construct(Request $request, SwaggerFormatter $formatter) { $this->request = $request; + $this->formatter = $formatter; } /** + * Format a collection of documentation data. + * * @param array $collection - * @param string $resource - * @return array + * @param null $resource + * @internal param $array [ApiDoc] $collection + * @return string|array */ - protected function produceApiDeclaration(array $collection, $resource) + public function format(array $collection, $resource = null) { - $data = parent::produceApiDeclaration($collection, $resource); - $data['basePath'] = $this->request->getBaseUrl() . $data['basePath']; - return $data; + $result = $this->formatter->format($collection, $resource); + + if ($resource !== null) { + $result['basePath'] = $this->request->getBaseUrl() . $result['basePath']; + } + + return $result; } -} \ No newline at end of file + + /** + * Format documentation data for one route. + * + * @param ApiDoc $annotation + * return string|array + */ + public function formatOne(ApiDoc $annotation) + { + return $this->formatter->formatOne($annotation); + } +} \ No newline at end of file diff --git a/Formatter/SwaggerFormatter.php b/Formatter/SwaggerFormatter.php index 9610141..078f098 100644 --- a/Formatter/SwaggerFormatter.php +++ b/Formatter/SwaggerFormatter.php @@ -14,9 +14,6 @@ namespace Nelmio\ApiDocBundle\Formatter; use Nelmio\ApiDocBundle\Annotation\ApiDoc; use Nelmio\ApiDocBundle\DataTypes; -use Symfony\Component\DependencyInjection\ContainerAwareInterface; -use Symfony\Component\DependencyInjection\ContainerInterface; -use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Router; use Symfony\Component\Routing\RouterInterface; @@ -57,11 +54,6 @@ class SwaggerFormatter implements FormatterInterface DataTypes::DATETIME => 'date-time', ); - /** - * @var Request - */ - protected $request; - /** * Format a collection of documentation data. * @@ -139,10 +131,11 @@ class SwaggerFormatter implements FormatterInterface * * @param ApiDoc $annotation * return string|array + * @throws \BadMethodCallException */ public function formatOne(ApiDoc $annotation) { - // TODO: Implement formatOne() method. + throw new \BadMethodCallException(sprintf('%s does not support formatting a single ApiDoc only.', __CLASS__)); } /** diff --git a/Resources/config/formatters.xml b/Resources/config/formatters.xml index 607be2f..93b9dd1 100644 --- a/Resources/config/formatters.xml +++ b/Resources/config/formatters.xml @@ -9,7 +9,6 @@ Nelmio\ApiDocBundle\Formatter\SimpleFormatter Nelmio\ApiDocBundle\Formatter\HtmlFormatter Nelmio\ApiDocBundle\Formatter\SwaggerFormatter - Nelmio\ApiDocBundle\Formatter\RequestAwareSwaggerFormatter null @@ -58,10 +57,8 @@ %nelmio_api_doc.sandbox.authentication% - - - - +