Merge pull request #1 from iadvize/IDZ-6717-Init

IDZ-6717 - init

.gitignore

@@ -0,0 +1,3 @@
+.idea
+vendor
+composer.lock

LICENCE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 iAdvize
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,2 +1,125 @@
 # php-swaggerize-fastroute-library
 A library to automatically create FastRoute routes based on swagger JSON documentation
+# Install
+To install with composer:
+```
+composer require iadvize/php-swaggerize-fastroute-library
+```
+
+# Generate route File (FastRoute compatible)
+
+```
+vendor/bin/swaggerize swagger:scan path/to/swagger/json controllers\namespace [--routeFile=route/file/path]
+```
+
+# Dispatch generated file or simply use cache
+
+You can then use FastRoute cached dispatcher to use generated file or directly use a cache dispatcher (file will be generated at first call).
+
+```PHP
+<?php
+
+require '/path/to/vendor/autoload.php';
+
+$lumenOperationParser = new \Iadvize\SwaggerizeFastRoute\OperationParser\LumenControllerOperationParser('Controllers\\Namespace\\');
+
+$dispatcher = FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r, ['cacheFile' => 'route/file/path']) {
+    \Iadvize\SwaggerizeFastRoute\addRoutes(
+        'path/to/swagger/json',
+         $r,
+         $lumenOperationParser,
+         ['routeFile' => 'path/to/generated/route/file', 'cacheEnabled' => false]
+     );
+});
+
+// Fetch method and URI from somewhere
+// ... see FastRoute Dispatcher
+```
+
+Alternatively to generate routes, you can simply cache first parse by setting `'cacheEnabled' => true` in addRoute function.
+
+# Apply this to Lumen application
+
+To use this swagger routes in a Lumen Application (which use FastRoute as route library), you need to extends `Laravel\Lumen\Application` and override `createDispatcher` method.
+
+```PHP
+
+<?php
+
+namespace My\Application;
+
+use Laravel\Lumen\Application as LumenApplication;
+
+/**
+ * Class Application
+ *
+ * @package My\Application
+ */
+class Application extends LumenApplication
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function createDispatcher()
+    {
+        return $this->dispatcher ?: \FastRoute\simpleDispatcher(function ($r) {
+            foreach ($this->routes as $route) {
+                $r->addRoute($route['method'], $route['uri'], $route['action']);
+            }
+
+            $operationParser = new \Iadvize\SwaggerizeFastRoute\OperationParser\LumenControllerOperationParser('My\Application\Http\Controllers');
+
+            \Iadvize\SwaggerizeFastRoute\addRoutes(storage_path('docs/definition.json'), $r, $operationParser, ['routeFile' => 'route/file/path']);
+        });
+    }
+}
+```
+
+# How handler is formed
+
+Handlers are formed from route defined in swagger as [Lumen](http://lumen.laravel.com/docs/routing#named-routes) define it for controller class : `Controller@method`
+### Controller class generation
+
+Controller class is determined from path route with first character uppercased and with Controller at the end of file name
+
+This swagger JSON :
+
+```JSON
+{
+// ...
+  "paths": {
+    "/pets": {
+      "get": {
+        // ...
+      }
+      "put": {
+        // ...
+      }
+    }
+    "/store": {
+      "post": {
+        // ...
+      }
+    }
+  }
+// ...
+}
+```
+
+will generates respectively this handlers:
+
+* `PetsController@get`
+* `PetsController@update`
+* `StoreController@create`
+
+### Method generation
+
+Controller method is mapped from HTTP method :
+* `GET`     => `get`,
+* `POST`    => `create`,
+* `PUT`     => `update`,
+* `HEAD`    => `head`,
+* `OPTIONS` => `options`,
+* `PATCH`   => `patch`,
+* `DELETE`  => `delete`,
+

bin/swaggerize

@@ -0,0 +1,7 @@
+#!/usr/bin/env php
+<?php
+require 'vendor/autoload.php';
+
+$app = new \Symfony\Component\Console\Application();
+$app->add(new \Iadvize\SwaggerizeFastRoute\Command\Scan());
+$app->run();

composer.json

@@ -0,0 +1,46 @@
+{
+  "name": "iadvize/php-swaggerize-fastroute-library",
+  "description": "A library to automatically create FastRoute routes based on swagger JSON documentation",
+  "authors": [
+    {
+      "name": "Marc FRICOU",
+      "email": "[email protected]"
+    }
+  ],
+
+  "repositories": [
+    {
+      "type": "git",
+      "url": "[email protected]:iadvize/lumen-doctrine.git"
+    },
+    {
+      "type": "git",
+      "url": "[email protected]:iadvize/api-swagger-ui.git"
+    },
+    {
+      "type": "git",
+      "url": "[email protected]:iadvize/standards.git"
+    }
+  ],
+  "require": {
+    "php": ">=5.5.21",
+    "nikic/fast-route": "0.*",
+    "thefrozenfire/swagger": "^2.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "~4.8",
+    "iadvize/standards": "dev-moveComposer",
+    "mockery/mockery": "~0.9",
+    "symfony/console": "^2.7"
+  },
+  "autoload": {
+    "psr-4": {
+      "Iadvize\\SwaggerizeFastRoute\\": "src/",
+      "IadvizeTest\\SwaggerizeFastRoute\\": "tests/"
+    },
+    "files": ["src/functions.php"]
+  },
+  "bin": [
+    "bin/swaggerize"
+  ]
+}

config/swaggerConfig.dist.php

@@ -0,0 +1,7 @@
+<?php
+
+return [
+    'routeFile'    => 'path/to/route/file',
+    'cacheEnabled' => true,
+    'namespace'    => 'Iadvize\ServiceNamespace',
+];

src/Command/Scan.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Iadvize\SwaggerizeFastRoute\Command;
+
+use Iadvize\SwaggerizeFastRoute\OperationParser\LumenControllerOperationParser;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Class Scan
+ *
+ * @package Iadvize\SwaggerizeFastRoute\Command
+ */
+class Scan extends Command
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function configure()
+    {
+        $this
+            ->setName('swagger:scan')
+            ->setDescription('Scan swagger JSON file ')
+            ->addArgument(
+                'swaggerFile',
+                InputArgument::REQUIRED,
+                'Give JSON file to scan'
+            )
+            ->addArgument(
+                'controllerNamespace',
+                InputArgument::REQUIRED,
+                'Controllers namespace that will handle route'
+            )
+            ->addOption(
+                'routeFile',
+                null,
+                InputOption::VALUE_REQUIRED,
+                'Where FastRoute cache file should be write ? Default to output'
+            );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $controllerNamespace = $input->getArgument('controllerNamespace');
+        $swaggerFile         = $input->getArgument('swaggerFile');
+        $routeStream         = $input->getOption('routeFile');
+
+        if (!$routeStream) {
+            $routeStream = 'php://output';
+        }
+
+        $operationParser = new LumenControllerOperationParser($controllerNamespace);
+
+        $routes = \Iadvize\SwaggerizeFastRoute\scan($swaggerFile, $operationParser);
+
+        \Iadvize\SwaggerizeFastRoute\cacheRoutes($routes, $routeStream);
+
+        if ($routeStream !== 'php://output') {
+            $output->writeln('route file available at ' . $routeStream);
+        }
+    }
+}

src/OperationParser/LumenControllerOperationParser.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace Iadvize\SwaggerizeFastRoute\OperationParser;
+
+use Swagger\OperationReference;
+
+/**
+ * Class LumenControllerOperationParser
+ *
+ * @package Iadvize\SwaggerizeFastRoute\OperationParser
+ */
+class LumenControllerOperationParser implements OperationParserInterface
+{
+
+    /** @var string */
+    protected $namespace;
+
+    /** @var array */
+    private $httpVerbToControllerMethod = [
+        'GET'     => 'get',
+        'POST'    => 'create',
+        'PUT'     => 'update',
+        'HEAD'    => 'head',
+        'OPTIONS' => 'options',
+        'PATCH'   => 'patch',
+        'DELETE'  => 'delete',
+    ];
+
+    /**
+     * Constructor
+     *
+     * @param string $controllerNamespace
+     */
+    public function __construct($controllerNamespace)
+    {
+        if (substr('$controllerNamespace', -1) !== '\\') {
+            $controllerNamespace .= '\\';
+        }
+
+        $this->namespace = $controllerNamespace;
+    }
+
+    /**
+     * Get Handler
+     *
+     * @param OperationReference $operation
+     *
+     * @return array
+     */
+    public function getHandler(OperationReference $operation)
+    {
+        // remove route parameters
+        $path = preg_replace('/\/\{.*\}/', '', $operation->getPath());
+
+        // lowerCamelCase to UpperCamelCase
+        $paths = explode('/', $path);
+        // path start with a /
+        unset($paths[0]);
+        $paths = array_map(function ($path) {
+            return ucfirst($path);
+        }, $paths);
+        // path to 'relative' namespace
+        $path = implode('\\', $paths);
+
+        $controller = $this->namespace . $path . 'Controller';
+
+        return ['uses' => $controller . '@' . $this->httpVerbToControllerMethod[strtoupper($operation->getMethod())], 'as' => $operation->getOperationId()];
+    }
+}

src/OperationParser/OperationParserInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Iadvize\SwaggerizeFastRoute\OperationParser;
+
+use Swagger\OperationReference;
+
+/**
+ * Interface OperationParserInterface
+ *
+ * @package Iadvize\SwaggerizeFastRoute\OperationParser
+ */
+interface OperationParserInterface
+{
+    /**
+     * Get Handler
+     *
+     * @param OperationReference $operation
+     *
+     * @return array
+     */
+    public function getHandler(OperationReference $operation);
+}