Nelmioapidocbundle: Document external dependencies routes

[MatthieuCutin]

Hey,

Thank you for this Bundle which i use in every of my projetcs.

I need to document some routes that are actually handled by some of my external bundles (ex: FOSUserBundle or LexikJWTAuthenticationBundle, ...) to show input/output parameters, test them in the sandbox and everything the ApiDoc allows me to do.

In order to do that i created a new service :

namespace Acseo\CoreBundle\Service;

use Nelmio\ApiDocBundle\Annotation\ApiDoc;
use Nelmio\ApiDocBundle\Extractor\AnnotationsProviderInterface;
use Symfony\Component\Finder\Finder;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Route;
use Symfony\Component\Yaml\Yaml;

/**
 * Generate annotations for vendor routes to be displayed in Nelmio ApiDoc.
 */
class NelmioApiYmlProvider implements AnnotationsProviderInterface
{
    private $vendorFolder;

    public function __construct($vendorFolder)
    {
        $this->vendorFolder = $vendorFolder;
    }
    /**
     * {@inheritdoc}
     */
    public function getAnnotations()
    {
        $annotations = [];
        $configDirectories = array($this->vendorFolder);

        $finder = new Finder();

        $finder->files()->in($configDirectories);

        if (count($finder) == 0) {
            throw new NotFoundHttpException('No file found for this protocol');
        }

        foreach ($finder as $file_) {
            $data = Yaml::parse(file_get_contents($file_));

            $vendors = array_keys($data);
            foreach ($vendors as $vendor) {
                $apiDoc = new ApiDoc($data[$vendor]);
                $route = new Route(
                    $data[$vendor]['route']['path'],
                    $data[$vendor]['route']['defaults'],
                    $data[$vendor]['route']['requirements'],
                    $data[$vendor]['route']['options'],
                    $data[$vendor]['route']['host'],
                    $data[$vendor]['route']['schemes'],
                    $data[$vendor]['route']['methods'],
                    $data[$vendor]['route']['condition']
                );

                $apiDoc->setRoute($route);
                $apiDoc->setResponse($data[$vendor]['response']);
                $annotations[] = $apiDoc;
            }
        }

        return $annotations;
    }
}

and declare it in my service.xml :

                <service id="nelmio_api_doc.yml_provider.acseo_yml_provider" class="%nelmio_api_doc.yml_provider.acseo_yml_provider.class%">
                    <argument>%nelmio_api_doc.vendors.folder%</argument>
                    <tag name="nelmio_api_doc.extractor.annotations_provider" />
                </service>

The nelmio_api_doc.vendors.folder parameter is set in the Dependency Injection process that i forked :
https://github.com/MatthieuCutin/NelmioApiDocBundle/blob/master/DependencyInjection/NelmioApiDocExtension.php
(line 32)
https://github.com/MatthieuCutin/NelmioApiDocBundle/blob/master/DependencyInjection/Configuration.php
(line 165)

But you may use the folder you want.

This allows me to write YAML files that contain any annotations already managed by the ApiDoc :

login_check:
    requirements: []
    views: []
    filters: []
    parameters:
        _password:
            dataType: string
            required: true
            name: _password
            description: Password
            readonly: false
        _username:
            dataType: string
            required: true
            name: _username
            description: Username
            readonly: false
    input: null
    output: null
    link: null
    description: "Get JWT token for logged user"
    section: "Session"
    documentation: null
    resource: null
    method: "POST"
    host: ""
    uri: "/login_check"
    response:
        token:
            dataType: string
            required: true
            description: JWT token
            readonly: true
    route:
        path: /login_check
        defaults:
            _controller: FOS\UserBundle\Controller\SecurityController::checkAction
        requirements: []
        options:
            compiler_class: Symfony\Component\Routing\RouteCompiler
        host: ''
        schemes: []
        methods: [ 'POST' ]
        condition: ''
    https: false
    authentication: false
    authenticationRoles: []
    cache: null
    deprecated: false
    statusCodes: []
    resourceDescription: null
    responseMap: []
    parsedResponseMap: []
    tags: []

Now i see my login_check route in my doc and i can use it with the sandbox and i'm happy with that :)

If you think this may be useful for the community i will be glad to make a PR.
Thank you @npotier for your help.

Thank you again for your Bundle !

[npotier]

Thanks @MatthieuCutin for this features and the mention. I'll be happy to see it merged or to have feedback from others.

[underq]

👍

[npotier]

@MatthieuCutin I think I would be great to make a PR for this feature.

What do you think about it @willdurand ?

[christian-kolb]

Would be great to have this as a feature. Looks like this fall down somewhere. Or is there another PR or issue solving this problem?

[dbu]

version 3 is now out and @GuilhemN is actively maintaining the bundle. the feature to define api docs outside of the controller files has been requested several times, so if one of the commenters in this issue can do a pull request, it would be appreciated.

[GuilhemN]

@dbu that's actually possible using the config in 3.0 :)

[dbu]

even better. thanks for the notice!

[kporras07]

@GuilhemN that's great! Do you have any working example? I need to do this :)

[GuilhemN]

@kporras07 config options are quickly described in https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#using-the-bundle, just have a look at the open api specification, you can define routes under paths as you want :)

[kporras07]

Awesome! Thanks :) It worked

[florianajir]

can anyone give a nelmio_api_doc config example ?

[kporras07]

Hi @florianajir
Maybe this helps: https://github.com/kporras07/notes-api/blob/master/config/packages/nelmio_api_doc.yaml

[florianajir]

Thank you @kporras07 this is working 😄

[dzetah]

@kporras07 Thanks for the hint, this should be in the docs.

If I have spare time, I'll do a PR to improve the docs, v3 docs feels a bit light to me.

Have a great day !