macpaw/behat-nelmio-describer

Bundle for adding sample responses behat test nelmio to api doc

v2.0.1 2023-12-01 09:22 UTC

Requires

• php: ^8.2
• nelmio/api-doc-bundle: ^4.0
• symfony/config: ^5.4 || ^6.0 || ^7.0
• symfony/dependency-injection: ^5.4 || ^6.0 || ^7.0
• symfony/routing: ^5.4 || ^6.0 || ^7.0

Requires (Dev)

• phpstan/phpstan: ^1.2
• phpunit/phpunit: ^9.5
• sensio/framework-extra-bundle: ^5.4 || ^6.0 || ^7.0
• slevomat/coding-standard: ^7.0
• squizlabs/php_codesniffer: ^3.6
• symfony/browser-kit: ^5.4 || ^6.0 || ^7.0
• symfony/console: ^5.4 || ^6.0 || ^7.0

MIT

• IiiigorGG
• Yozhef Hisem

• symfony
• Behat
• swagger
• symfony-bundle
• api-doc
• nelmio
• MacPaw

README

Installation

Step 1: Install Bundle

Open a command console, enter your project directory and execute:

$ composer require macpaw/behat-nelmio-describer

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            BehatNelmioDescriber\BehatNelmioDescriberBundle::class => ['all' => true]
        );

        // ...
    }

    // ...
}

Step 3: Create Behat Nelmio Describer Config:

config/packages/behat_nelmio_describer.yaml

Configurating behat nelmio describer

behat_nelmio_describer:
  behat_test_path: <path to directory with your behat features>

Step 4: Add annotation to controller [OPTIONAL]

<?php

use BehatNelmioDescriber\Attributes\BehatFeaturesPath;

#[BehatFeaturesPath(path: "<path to folder/file with fixtures regarding base path in config>")]
final class SomeController extends AbstractController{
    // ... 
}

Step 5: Add annotation to route

<?php

use BehatNelmioDescriber\Attributes\BehatFeature;
use BehatNelmioDescriber\Enum\Status;

final class SomeController extends AbstractController{
    #[BehatFeature(status: "<string name to group by>", file: '<filename or route to file regarding base path>', anchors: [
       // array of anchors    
    ])]
    public function handleRequestFunction() {
        // ...
    }
}

For each anchor path from config, path from BehatFeaturesPath annotation (optional) and path/filename from BehatFeature annotation are concatenated to find the right feature file.

Additionally, each BehatFeature annotation represents folder in api doc which contains all sample responses defined by anchors.

An example of usage

If your feature file is located in src/tests/Behat/Features/api/version/route/example.feature

Configuration

behat_nelmio_describer:
  behat_test_path: '%kernel.project_dir%/tests/Behat/Features'

Used in Controller:

<?php

namespace Some/Namespace;

use BehatNelmioDescriber\Attributes\BehatFeature;
use BehatNelmioDescriber\Attributes\BehatFeaturesPath;
use FOS\RestBundle\Controller\Annotations as Rest;
use Nelmio\ApiDocBundle\Annotation as ApiDoc;
use OpenApi\Annotations as OA;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

#[Route(path: '/api/version/route', name: 'api_version_route_')]
#[BehatFeaturesPath(path: 'api/version/route/')]
final class CustomerController extends AbstractController
{
    /**
     * Title
     *
     * @Route(
     *     path="/example",
     *     name="example",
     *     defaults={"_format": "json"},
     *     methods={"GET"}
     * )
     *
     * @ApiDoc\Operation(tags={"Example"})
     */
    #[BehatFeature(status: Status::SUCCESS, file: 'example.feature', anchors: [
       'success',
       'successWithoutOptionalParams',    
    ])]
    #[BehatFeature(status: Status::FAILURE, file: 'example.feature', anchors: [
       'paramsInvalid',    
    ])]
    public function getCustomerProductPlanListAction(
        // ...
    ) {
        // ...
    }
}

Update your feature file:

Contains following snippets:

#! success
"""
{
    "example": "data""
}
"""

#! successWithoutOptionalParams
"""
{
    "example": "data""
}
"""

#! paramsInvalid
"""
{
    "example": "data""
}
"""

Now in Api Doc see response payload your test: