README

简介

Silex 注释 是一种简单配置 Silex 路由的方法。结合此桥接器以及 Swagger-PHP，可以从这些注释中轻松生成基本的 swagger 文档。

通常，Swagger 注释添加到现有的 Silex 注释之上，以补充/完成定义。

对于 OpenApi 3.0 和对其他框架的支持，请使用 radebatz/openapi-router

混合 Silex 和 Swagger 注释

<?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) {
    ...

将 Swagger 属性附加到 Silex Request

Silex2Swagger 提供了一个自定义的 Request 注解，允许将任何支持的 Swagger 属性附加到请求。只需使用 Silex Request 注解的自定义实现即可。

<?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) 
    {
        ...
    }

在控制器内设置常用参数/响应

如果您在控制器中的所有端点上都需要参数，可以在控制器级别定义这些参数以避免代码重复。

为此，有一个 自定义 的 Controller 注解类，允许嵌套 Swagger 参数。这样定义的所有参数都将注入到控制器类内部的所有路由中。

<?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 {
    ...
}

生成 Swagger

使用 CL

./bin/silex2swagger silex2swagger:build --path=[src] --file=swagger.json

使用（简单）代码

<?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;

有关更完整的示例，请参阅包含的 Symfony Console 命令。

注意事项

• 所有注释类都需要在类路径中（由自动加载器可见）。
• 为了准确合并/分组注释，需要使用 @SLX\Route 示例

    /**
     * @SLX\Route(
     *   @SLX\Request(method="GET", uri="/foo"),
     *   @SLX\RequireHttp,
     *   @SWG\Response()
     * )
     */

变更日志

v1.0.0

• 初始版本

v1.0.1

• 使命令更加可定制

v1.0.2

• 添加对 Bind 注释的支持（设置为 operationId）
• 如果不存在，允许自动生成描述和/或摘要

v1.0.3

• 支持回调以收集要添加的额外（自定义）数据（例如：标签等）

v2.0.0

• 为 Silex 2 更新依赖项

v2.0.1

• 将 ddesrosiers/silex-annotation-provider 的依赖项更新到官方 2.0 版本

v2.0.2

• 修复使用 @Controller 无前缀创建双斜杠的问题

v3.0.0

• 引入唯一命名空间并进行清理
• 添加支持所有 Swagger 属性的自定义 Swagger-PHP 请求注解
• 将 PHP 要求提升到 PHP 5.6

v3.0.1

• 修复控制器类需要使用 FQCN 进行比较的 bug
• 允许在控制器内部共享参数和响应 [#9]

v3.0.2

• 允许通过 @S2S\SwaggerProperty 设置所有公共请求属性 [#12]

v3.0.3

• 允许在命令行上指定多个源位置 [#14]

v3.0.4

• 最终合并自动生成和注解的参数定义 [#16]

v3.0.5

• 代码清理