From 0e01a00aaf5c25480144c0ff5f06f173fa640300 Mon Sep 17 00:00:00 2001 From: Bez Hermoso Date: Thu, 31 Jul 2014 12:27:40 -0700 Subject: [PATCH] Behavior and usage updates. --- Command/SwaggerDumpCommand.php | 104 ++++++++++++++----------------- Resources/doc/swagger-support.md | 6 +- 2 files changed, 49 insertions(+), 61 deletions(-) diff --git a/Command/SwaggerDumpCommand.php b/Command/SwaggerDumpCommand.php index 2a661ab..f5c0704 100644 --- a/Command/SwaggerDumpCommand.php +++ b/Command/SwaggerDumpCommand.php @@ -11,16 +11,17 @@ namespace Nelmio\ApiDocBundle\Command; +use Nelmio\ApiDocBundle\Formatter\SwaggerFormatter; use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; +use Symfony\Component\Console\Input\InputArgument; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Input\InputOption; use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Filesystem\Exception\IOException; use Symfony\Component\Filesystem\Filesystem; - /** - * Symfony2 command to dump Swagger-compliant JSON files. + * Console command to dump Swagger-compliant API definitions. * * @author Bez Hermoso */ @@ -31,17 +32,21 @@ class SwaggerDumpCommand extends ContainerAwareCommand */ protected $filesystem; - protected $destination; + /** + * @var SwaggerFormatter + */ + protected $formatter; protected function configure() { $this->filesystem = new Filesystem(); $this - ->setDescription('Dump Swagger-compliant JSON files.') - ->addOption('resource', '', InputOption::VALUE_OPTIONAL, 'A specific resource API declaration to dump.') - ->addOption('list-only', '', InputOption::VALUE_NONE, 'Dump resource list only.') - ->addArgument('destination', InputOption::VALUE_OPTIONAL, 'Directory to dump JSON files in.', null) + ->setDescription('Dumps Swagger-compliant API definitions.') + ->addOption('resource', 'r', InputOption::VALUE_OPTIONAL, 'A specific resource API declaration to dump.') + ->addOption('list-only', 'l', InputOption::VALUE_NONE, 'Dump resource list only.') + ->addOption('pretty', 'p', InputOption::VALUE_NONE, 'Dump as prettified JSON.') + ->addArgument('destination', InputArgument::OPTIONAL, 'Directory to dump JSON files in.', null) ->setName('api:swagger:dump'); } @@ -50,26 +55,7 @@ class SwaggerDumpCommand extends ContainerAwareCommand $container = $this->getContainer(); $extractor = $container->get('nelmio_api_doc.extractor.api_doc_extractor'); - - $destination = $input->getArgument('destination'); - - if (count($destination) > 0) { - - $destination = $destination[0]; - - $realpath = realpath($destination); - - if ($realpath == false) { - $rootDir = $container->getParameter('kernel.root_dir'); - $rootDir = realpath($rootDir . '/..'); - $destination = $rootDir . '/' . $destination; - } else { - $destination = $realpath; - } - $this->destination = $destination; - } else { - $this->destination = null; - } + $this->formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter'); if ($input->getOption('list-only') && $input->getOption('resource')) { throw new \RuntimeException('Cannot selectively dump a resource with the --list-only flag.'); @@ -92,9 +78,12 @@ class SwaggerDumpCommand extends ContainerAwareCommand return; } + /* + * If --list-only and --resource is not specified, dump everything. + */ $data = $this->getResourceList($apiDocs); - if ($this->destination == null) { + if (!$input->getArguments('destination')) { $output->writeln(''); $output->writeln('Resource list: '); } @@ -104,7 +93,7 @@ class SwaggerDumpCommand extends ContainerAwareCommand foreach ($data['apis'] as $api) { $resource = substr($api['path'], 1); - if ($this->destination == null) { + if (!$input->getArgument('destination')) { $output->writeln(''); $output->writeln(sprintf('API declaration for "%s" resource: ', $resource)); } @@ -115,61 +104,60 @@ class SwaggerDumpCommand extends ContainerAwareCommand protected function dump(array $data, $resource, InputInterface $input, OutputInterface $output, $treatAsFile = true) { + $destination = $input->getArgument('destination'); - $content = json_encode($data, JSON_PRETTY_PRINT); + $content = json_encode($data, $input->getOption('pretty') ? JSON_PRETTY_PRINT : 0); - if ($this->destination == null) { + if (!$destination) { $output->writeln($content); return; } - if ($resource == false) { - if ($treatAsFile === false) { - $path = sprintf('%s/api-docs.json', $this->destination); - } else { - $path = $this->destination; + if ($treatAsFile === false) { + if (!$this->filesystem->exists($destination)) { + $this->filesystem->mkdir($destination); } - $string = sprintf('Dumping resource list to %s: ', $path); - $this->writeToFile($data, $path, $output, $string); + } + + if (!$resource) { + + if (!$treatAsFile) { + $destination = sprintf('%s/api-docs.json', rtrim($destination, '\\/')); + } + $message = sprintf('Dumping resource list to %s: ', $destination); + $this->writeToFile($content, $destination, $output, $message); + return; } if ($treatAsFile === false) { - $path = sprintf('%s/%s.json', $this->destination, $resource); - } else { - $path = $this->destination; + $destination = sprintf('%s/%s.json', rtrim($destination, '\\/'), $resource); } - $string = sprintf('Dump API declaration to %s: ', $path); - $this->writeToFile($content, $path, $output, $string); + + $message = sprintf('Dump API declaration to %s: ', $destination); + $this->writeToFile($content, $destination, $output, $message); } - protected function writeToFile($content, $file, OutputInterface $output, $string = null) + protected function writeToFile($content, $file, OutputInterface $output, $message) { - $message = array($string); try { $this->filesystem->dumpFile($file, $content); - $message[] = 'OK'; - $output->writeln(implode(' ', array_filter($message))); + $message .= ' OK'; } catch (IOException $e) { - $message[] = 'NOT OK'; - $output->writeln(implode(' ', array_filter($message))); + $message .= sprintf(' NOT OK - %s', $e->getMessage()); } + + $output->writeln($message); } protected function getResourceList(array $data) { - $container = $this->getContainer(); - $formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter'); - $list = $formatter->format($data); - return $list; + return $this->formatter->format($data); } protected function getApiDeclaration(array $data, $resource) { - $container = $this->getContainer(); - $formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter'); - $list = $formatter->format($data, '/' . $resource); - return $list; + return $this->formatter->format($data, '/' . $resource); } -} \ No newline at end of file +} diff --git a/Resources/doc/swagger-support.md b/Resources/doc/swagger-support.md index b2b50fe..b543519 100644 --- a/Resources/doc/swagger-support.md +++ b/Resources/doc/swagger-support.md @@ -80,7 +80,7 @@ Et voila!, simply specify http://yourdomain.com/api-docs in your Swagger client The routes registered with the method above will read your `@ApiDoc` annotation during every request. Naturally, this will be slow because the bundle will parse your annotations every single time. For improved performance, you might be better off dumping the JSON output to the file-system and let your web-server serve them directly. If you want that, execute this command: ``` -php app/console api:swagger:dump --all app/Resources/swagger-docs +php app/console api:swagger:dump app/Resources/swagger-docs ``` The above command will dump JSON files under the `app/Resources/swagger-docs` directory (relative to your project root), and you can now process or server the files however you want. The destination defaults to the project root if not specified. @@ -89,12 +89,12 @@ The above command will dump JSON files under the `app/Resources/swagger-docs` di Dump the `api-docs.json` resource list file only: ``` -php app/console api:swagger:dump --list-only +php app/console api:swagger:dump --list-only api-docs.json ``` Dump a specific resource API declaration only: ``` -php app/console api:swagger:dump --resource=users +php app/console api:swagger:dump --resource=users users.json ``` The above command will dump the `/users` API declaration in an `users.json` file.