README

👁 Build Status

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