README

此包旨在防止使用您的真实控制器进行请求，并以您定义的假响应进行响应。它很好地与NelmioApiDocBundle和FOSRestBundle集成。

当使用NelmioApiDocBundle时，此包将自动为您提供的沙箱请求生成curl示例，并在文档中显示。

要求

ApiSandboxBundle需要php >= 5.5和symfony >= 2.7。

安装

安装此库的最简单方法是通过composer。只需将以下行添加到您的composer.json文件中，然后运行composer.phar update

{
   "require": {
        "bpa/api-sandbox-bundle": "dev-master"
    }
}

配置

在您的AppKernel.php中加载此包

class AppKernel extends Kernel {
    public function registerBundles() {
        // ...
        $bundles = [
            // ... 
            new Bpa\ApiSandboxBundle\ApiSandboxBundle(),
            // ...
        ];
        // ...
    }
}

我建议通过复制app.php前端控制器到类似app_sandbox.php的内容来为您的沙箱创建一个新环境。在您的新前端控制器中，您必须将以下行更改为新环境

$kernel = new AppKernel('sandbox', false);

在您的app/config目录中创建一个新的config_sandbox.yml，内容如下

imports:
    - { resource: config_prod.yml }

api_sandbox:
    enabled: true
    force_response: true

这将从您的prod环境获取所有设置并启用新sandbox环境中的沙箱。

用法

基本控制器

当使用FOSRestBundle和NelmioApiDocBundle为您的API时，您的应用程序中的集成可能如下所示

<?php

namespace AppBundle\Controller;

use Nelmio\ApiDocBundle\Annotation\ApiDoc;
use Bpa\ApiSandboxBundle\Annotation as Bpa;
use FOS\RestBundle\Controller\FOSRestController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

/**
 * Controller for books
 */
class BookController extends FOSRestController
{
    /**
     * Get book informations
     *
     * Retrieve informations about a specific book
     *
     * @ApiDoc(
     *     section="Books",
     *     resource=true,
     *     statusCodes={
     *         200="Ok",
     *     }
     * )
     *
     * @Bpa\SandboxRequest(
     *     responses={
     *         @Bpa\SandboxResponse(
     *             statusCode=200,
     *             content="@AppBundle/Resources/sandbox/responses/books/get.json",
     *         )
     *     }
     * )
     *
     * @param Request $request
     *
     * @return JsonResponse
     */
    public function getAction(Request $request)
    {
        return new JsonResponse([
            'books' => [ 'id' => 1, 'title' => 'A Brief History of Time' ],
        ]);        
    }
}

使用参数

您可以定义单个控制器动作的多个响应，并通过使用类似这样的SandboxRequest\Parameter注解来区分它们

<?php

class BookController extends FOSRestController
{
    /**
     * ...
     * 
     * @Bpa\SandboxRequest(
     *    responses={
     *        @Bpa\SandboxResponse(
     *            statusCode=200,
     *            content="@AppBundle/Resources/sandbox/responses/books/get_1.json",
     *            parameters={
     *                @Bpa\SandboxRequest\Parameter(name="id", value="1"),
     *            }
     *        ),
     *        @Bpa\SandboxResponse(
     *            statusCode=200,
     *            content="@AppBundle/Resources/sandbox/responses/books/get_2.json",
     *            parameters={
     *                @Bpa\SandboxRequest\Parameter(name="id", value="2"),
     *            }
     *        ),
     *        @Bpa\SandboxResponse(
     *            statusCode=200,
     *            content="@AppBundle/Resources/sandbox/responses/books/get.json",
     *        )
     *    }
     * )
     *
     * ...
     */
    public function getAction(Request $request) { /* ... */ }
}

如果您现在提供参数id = 1，则返回第一个响应。使用id = 2返回第二个响应，对于所有其他请求返回第三个响应。

自动生成文档

设置好所有这些后，您将自动看到使用NelmioApiDocBundle生成的示例API文档。如果您为您的文档设计了自定义主题，您可以为提供自己的ExampleGenerator，该生成器仅应扩展提供的ExampleGenerator并覆盖buildExample方法

<?php

namespace DocBundle\Service\ApiDoc\Extractor;

use Bpa\ApiSandboxBundle\Annotation\SandboxResponse;
use Bpa\ApiSandboxBundle\Service\ApiDoc\Extractor\ExampleGenerator as BaseGenerator;
use Symfony\Component\Routing\Route;

class ExampleGenerator extends BaseGenerator
{
    /**
     * @param Route           $route
     * @param SandboxResponse $response
     *
     * @return mixed|string
     */
    protected function buildExample(Route $route, SandboxResponse $response)
    {
        return 'Your custom example markdown';
    }
}

贡献

请随时为此包做出贡献。任何贡献都将非常受赞赏，并将得到审查。