radebatz / silex2swagger
Generate swagger documentation from Silex Annotations
Installs: 7 308
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 2
Forks: 2
Open Issues: 1
Requires
- php: >=5.6
- ddesrosiers/silex-annotation-provider: ~2.0
- psr/log: ^1.0
- zircote/swagger-php: ~2.0
Requires (Dev)
- phpunit/phpunit: ~5.0
- satooshi/php-coveralls: ^1.0
- symfony/console: ~2.8|3.0.0
README
Introduction
Silex Annotations are an easy way to configure routes in Silex. With this bridge, in combination with Swagger-PHP, it is easy to generate basic swagger documentation from these annotations.
Typically the Swagger annotations are added on top of existing Silex annotations to complement/complete the definitions.
For OpenApi 3.0 and support for other frameworks use radebatz/openapi-router
Mixing Silex and Swagger annotations
<?php namespace mycode; use Silex\Application; use Symfony\Component\HttpFoundation\Request; use Swagger\Annotations as SWG; use DDesrosiers\SilexAnnotations\Annotations as SLX; class Controller { /** * Update. * * @SLX\Route( * @SLX\Request(method="PUT", uri="/{id}"), * * @SWG\Parameter( * name="Pet", * in="body", * description="Pet to update", * required=true, * @SWG\Schema(ref="#/definitions/Pet") * ), * * @SWG\Response(response=200, description="The full updated Pet", @SWG\Schema(ref="#/definitions/Pet")), * @SWG\Response(response="default", description="Error", @SWG\Schema(ref="#/definitions/jsonError")) * ) */ public function update(Application $app, Request $request, $id) { ...
Attaching Swagger properties to a Silex Request
Silex2Swagger provides a custom Request
annotation that allows to attach any supported
Swagger property to a request. All that is required is to use a custom implementation of the
Silex Request
annotation.
<?php namespace mycode; use Silex\Application; use Symfony\Component\HttpFoundation\Request; use Swagger\Annotations as SWG; use DDesrosiers\SilexAnnotations\Annotations as SLX; use Radebatz\Silex2Swagger\Swagger\Annotations as S2S; class Controller { /** * Update. * * @SLX\Route( * @S2S\Request(method="POST", uri="/login", * @S2S\SwaggerProperty(name="consumes", value={"application/x-www-form-urlencoded"}) * ), * * @SWG\Parameter( * name="email", * in="formData", * description="Email address", * required=true, * type="string" * ), * @SWG\Parameter( * name="password", * in="formData", * description="Password", * required=true, * type="string" * ) * ) */ public function update(Application $app, Request $request) { ... }
Setting up common parameters/responses within a Controller
If you have parameters required on all endpoints in a controller it is possible to define those on controller level to avoid code duplication.
In order to do this there is a custom Controller
annotation class that allows nested swagger parameters.
All parameters defined that way will be injected into all routes inside the controller class.
<?php namespace mycode; use Radebatz\Silex2Swagger\Swagger\Annotations as S2S; use Swagger\Annotations as SWG; /** * @S2S\Controller( * @SWG\Parameter( * name="x-api-version", * in="header", * required=true, * type="string" * ), * @SWG\Response( * response=401, * description="not authorized" * ) * ) */ class MyController { ... }
Generating Swagger
Using the CL
./bin/silex2swagger silex2swagger:build --path=[src] --file=swagger.json
Using (simple) code
<?php require 'vendor/autoload.php'; use Silex\Application; use Radebatz\Silex2Swagger\Swagger\S2SAnalysis; use Radebatz\Silex2Swagger\Swagger\S2SConverter; $swagger = \Swagger\scan('./src', ['analysis' => new S2SAnalysis([], null, new S2SConverter(new Application()))]); echo $swagger;
For a more complete example have a look at the included Symfony Console command.
Gotchas
- All annotation classes need to be in the class path (visible by the auto loader).
- In order to accurately merge/group annotations it is necessary to use the
@SLX\Route
Example:
/** * @SLX\Route( * @SLX\Request(method="GET", uri="/foo"), * @SLX\RequireHttp, * @SWG\Response() * ) */
Changelog
v1.0.0
- Initial version
v1.0.1
- Make command more customizable
v1.0.2
- Add support for Bind annotation (set as operationId)
- Allow to auto generate description and/or summary if not present
v1.0.3
- Support callback to collect additional (custom) data to be added (ie: tags, etc.)
v2.0.0
- Update dependencies for Silex 2
v2.0.1
- Update dependencies for ddesrosiers/silex-annotation-provider to the official 2.0 version
v2.0.2
- Fix double slash being created using
@Controller
without a prefix
v3.0.0
- Introduce unique namespace and cleanup
- Add custom Swagger-PHP Request annotation that supports all swagger properties
- Bump PHP requirements to PHP 5.6
v3.0.1
- Fix bug where controller classes need to be compared using FQCN
- Allow to share parameters and responses within a controller [#9]
v3.0.2
- Allow to set all public request properties via @S2S\SwaggerProperty [#12]
v3.0.3
- Allow to specify multiple source locations on command line [#14]
v3.0.4
- Finally merge auto-generated and annotated parameter definitions [#16]
v3.0.5
- Code cleanup