This bundle is designed to prevent requests using your real controllers and responding with a fake
response you defined. It integrates nicely with NelmioApiDocBundle
and FOSRestBundle
.
When using NelmioApiDocBundle
this bundle will generate curl
examples for your provided sandbox
requests automatically which will show in the documentation.
ApiSandboxBundle requires php >= 5.5 and symfony >= 2.7.
The easiest way to install this library is through composer.
Just add the following lines to your composer.json file and run composer.phar update
:
{
"require": {
"bpa/api-sandbox-bundle": "dev-master"
}
}
Load the bundle in your AppKernel.php
:
class AppKernel extends Kernel {
public function registerBundles() {
// ...
$bundles = [
// ...
new Bpa\ApiSandboxBundle\ApiSandboxBundle(),
// ...
];
// ...
}
}
I would recommend to create a new environment for your sandbox by copying the app.php
front controller
to something like app_sandbox.php
. In your new front controller you have to change the following line
to the new environment:
$kernel = new AppKernel('sandbox', false);
Create a new config_sandbox.yml
in your app/config
directory with the following contents:
imports:
- { resource: config_prod.yml }
api_sandbox:
enabled: true
force_response: true
This takes all settings from your prod
environment and enables the sandbox for your new sandbox
environment.
When using the FOSRestBundle
and NelmioApiDocBundle
for your API an integration within your
application could look something like this:
<?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' ],
]);
}
}
It's possible to define multiple responses for a single Controller action and distinguish between
them by using the SandboxRequest\Parameter
Annotation like this:
<?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) { /* ... */ }
}
If you now provide the parameter id = 1
the first response will be returned. With id = 2
the second
one is returned and for all other requests the third response will be returned.
With all this set up you will see automatically generated examples API documentation with
the NelmioApiDocBundle
. If you designed your own theme for your documentation you are able
to provide your own ExampleGenerator
which only should extend the provided ExampleGenerator
and override the buildExample
method:
<?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';
}
}
Please feel free to contribute to this bundle. Any contribution is highly appreciated and will be reviewed.