README

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.

Requirements

ApiSandboxBundle requires php >= 5.5 and symfony >= 2.7.

Installation

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"
    }
}

Configuration

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.

Usage

A basic Controller

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' ],
        ]);        
    }
}

Using parameters

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.

Automatic generation of documentation

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';
    }
}

Contributing

Please feel free to contribute to this bundle. Any contribution is highly appreciated and will be reviewed.

bpa / api-sandbox-bundle

Maintainers

Details