Merge pull request #455 from bezhermoso/swagger-dump-command

api:swagger:dump update

Command/SwaggerDumpCommand.php

@@ -11,122 +11,153 @@
 
 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 <bez@activelamp.com>
  */
 class SwaggerDumpCommand extends ContainerAwareCommand
 {
+    /**
+     * @var Filesystem
+     */
+    protected $filesystem;
+
+    /**
+     * @var SwaggerFormatter
+     */
+    protected $formatter;
+
     protected function configure()
     {
+        $this->filesystem = new Filesystem();
+
         $this
-            ->setDescription('Dump Swagger-compliant JSON files.')
+            ->setDescription('Dumps Swagger-compliant API definitions.')
-            ->addOption('resource', '', InputOption::VALUE_OPTIONAL, 'A specific resource API declaration to dump.')
+            ->addOption('resource', 'r', InputOption::VALUE_OPTIONAL, 'A specific resource API declaration to dump.')
-            ->addOption('all', '', InputOption::VALUE_NONE, 'Dump resource list and all API declarations.')
+            ->addOption('list-only', 'l', InputOption::VALUE_NONE, 'Dump resource list only.')
-            ->addOption('list-only', '', InputOption::VALUE_NONE, 'Dump resource list only.')
+            ->addOption('pretty', 'p', InputOption::VALUE_NONE, 'Dump as prettified JSON.')
-            ->addArgument('destination', InputOption::VALUE_REQUIRED, 'Directory to dump JSON files in.', null)
+            ->addArgument('destination', InputArgument::OPTIONAL, 'Directory to dump JSON files in.', null)
             ->setName('api:swagger:dump');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         $container = $this->getContainer();
-        $destination = $input->getArgument('destination');
 
-        $rootDir = $container->get('kernel')->getRootDir();
+        $extractor = $container->get('nelmio_api_doc.extractor.api_doc_extractor');
-        $rootDir = $rootDir . '/..';
+        $this->formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter');
-
-        if (null === $destination) {
-            $destination = realpath($rootDir . '/' . $destination);
-        }
-
-        $fs = new Filesystem();
-
-        if (!$fs->exists($destination)) {
-            $fs->mkdir($destination);
-        }
-
-        $destination = realpath($destination);
-
-        if ($input->getOption('all') && $input->getOption('resource')) {
-            throw new \RuntimeException('Cannot selectively dump a resource with the --all flag.');
-        }
 
         if ($input->getOption('list-only') && $input->getOption('resource')) {
             throw new \RuntimeException('Cannot selectively dump a resource with the --list-only flag.');
         }
 
-        if ($input->getOption('all') && $input->getOption('list-only')) {
+        $apiDocs = $extractor->all();
-            throw new \RuntimeException('Cannot selectively dump resource list with the --all flag.');
-        }
-
-        $output->writeln('');
-        $output->writeln('Reading annotations...');
-        $extractor = $container->get('nelmio_api_doc.extractor.api_doc_extractor');
-        $data = $extractor->all();
 
         if ($input->getOption('list-only')) {
-             $this->dumpResourceList($destination, $data, $output);
+            $data = $this->getResourceList($apiDocs, $output);
+            $this->dump($data, null, $input, $output);
+            return;
         }
 
         if (false != ($resource = $input->getOption('resource'))) {
-            $this->dumpApiDeclaration($destination, $data, $resource, $output);
+            $data = $this->getApiDeclaration($apiDocs, $resource, $output);
+            if (count($data['apis']) === 0) {
+                throw new \InvalidArgumentException(sprintf('Resource "%s" does not exist.', $resource));
+            }
+            $this->dump($data, $resource, $input, $output);
+            return;
         }
 
-        if ($input->getOption('all')) {
+        /*
-            $formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter');
+         * If --list-only and --resource is not specified, dump everything.
-            $this->dumpResourceList($destination, $data, $output);
+         */
-            $list = $formatter->format($data);
+        $data = $this->getResourceList($apiDocs);
-            foreach ($list['apis'] as $api) {
+
-                $this->dumpApiDeclaration($destination, $data, substr($api['path'], 1), $output);
+        if (!$input->getArguments('destination')) {
+            $output->writeln('');
+            $output->writeln('<comment>Resource list: </comment>');
         }
+
+        $this->dump($data, null, $input, $output, false);
+
+        foreach ($data['apis'] as $api) {
+
+            $resource = substr($api['path'], 1);
+            if (!$input->getArgument('destination')) {
+                $output->writeln('');
+                $output->writeln(sprintf('<comment>API declaration for <info>"%s"</info> resource: </comment>', $resource));
+            }
+            $data = $this->getApiDeclaration($apiDocs, $resource, $output);
+            $this->dump($data, $resource, $input, $output, false);
         }
     }
 
-    protected function dumpResourceList($destination, array $data, OutputInterface $output)
+    protected function dump(array $data, $resource, InputInterface $input, OutputInterface $output, $treatAsFile = true)
     {
-        $container = $this->getContainer();
+        $destination = $input->getArgument('destination');
-        $formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter');
 
-        $list = $formatter->format($data);
+        $content = json_encode($data, $input->getOption('pretty') ? JSON_PRETTY_PRINT : 0);
 
-        $fs = new Filesystem();
+        if (!$destination) {
-        $path = $destination . '/api-docs.json';
+            $output->writeln($content);
-
+            return;
-        $string = sprintf('<comment>Dump resource list to %s: </comment>', $path);
-        try {
-            $fs->dumpFile($path, json_encode($list));
-        } catch (IOException $e) {
-            $output->writeln($string . ' <error>NOT OK</error>');
-        }
-        $output->writeln($string . '<info>OK</info>');
         }
 
-    protected function dumpApiDeclaration($destination, array $data, $resource, OutputInterface $output)
+        if ($treatAsFile === false) {
+            if (!$this->filesystem->exists($destination)) {
+                $this->filesystem->mkdir($destination);
+            }
+        }
+
+        if (!$resource) {
+
+            if (!$treatAsFile) {
+                $destination = sprintf('%s/api-docs.json', rtrim($destination, '\\/'));
+            }
+            $message = sprintf('<comment>Dumping resource list to %s: </comment>', $destination);
+            $this->writeToFile($content, $destination, $output, $message);
+
+            return;
+        }
+
+        if ($treatAsFile === false) {
+            $destination = sprintf('%s/%s.json', rtrim($destination, '\\/'), $resource);
+        }
+
+        $message = sprintf('<comment>Dump API declaration to %s: </comment>', $destination);
+        $this->writeToFile($content, $destination, $output, $message);
+
+    }
+
+    protected function writeToFile($content, $file, OutputInterface $output, $message)
     {
-        $container = $this->getContainer();
-        $formatter = $container->get('nelmio_api_doc.formatter.swagger_formatter');
-
-        $list = $formatter->format($data, '/' . $resource);
-
-        $fs = new Filesystem();
-        $path = sprintf($destination . '/%s.json', $resource);
-
-        $string = sprintf('<comment>Dump API declaration to %s: </comment>', $path);
         try {
-            $fs->dumpFile($path, json_encode($list));
+            $this->filesystem->dumpFile($file, $content);
+            $message .= ' <info>OK</info>';
         } catch (IOException $e) {
-            $output->writeln($string . ' <error>NOT OK</error>');
+            $message .= sprintf(' <error>NOT OK - %s</error>', $e->getMessage());
         }
-        $output->writeln($string . '<info>OK</info>');
+
+        $output->writeln($message);
+    }
+
+    protected function getResourceList(array $data)
+    {
+        return $this->formatter->format($data);
+    }
+
+    protected function getApiDeclaration(array $data, $resource)
+    {
+        return $this->formatter->format($data, '/' . $resource);
     }
 }

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.