Discussion on: Use Swagger to document a Symfony API

[plesiosaure]

Hello,

This approach is really interesting. Thank you for sharing. I also encountered some problems with Nelmio 2 not compatible with symfony 3.4 (seems to use old templating system) but Nelmio 3 use @SWG annotations.
Nevertheless, if you are in my case and had already used annotations @Rest\Get and
@Rest\QueryParam to simplify the code in the controller thanks to FosRest, how to avoid doubling annotations to generate a doc ? any idea ? thanks

[Mathieu Ferment]

Symfony3 documentation seems to suggest Nelmio 3 is able to parse FOSRest annotation, and to generate a Swagger JSON file accordingly.

This tutorial, in French unfortunately, says that it uses @Rest\QueryParam and that Nelmio is able to export it using as a Swagger file.

I will give it a try this weekend. If this does not work, we know that Nelmio can read FOSRest annotations and generate the right HTML doc from it. So I guess the best would be to make a PR to Nelmio project to allow this behavior.

[Mathieu Ferment]

I created a basic Symfony4 API using FOSRestBundle 2.3.1 and NelmioApiDocBundle 3.1. I confirm Nelmio was able to parse my FOS\RestBundle\Controller\Annotations\QueryParam annotation and generate the right doc.

My Controller:

<?php

namespace App\Controller;

use FOS\RestBundle\Request\ParamFetcher;
use FOS\RestBundle\Controller\Annotations\RequestParam;
use FOS\RestBundle\Controller\Annotations\QueryParam;
use FOS\RestBundle\Controller\Annotations\FileParam;
use Acme\FooBundle\Validation\Constraints\MyComplexConstraint;

use Symfony\Component\Routing\Annotation\Route;

class FooController
{
    /**
     * @QueryParam(name="page", requirements="\d+", default="1", description="Page of the overview.")
     * @Route("/api/rewards", methods={"GET"})
     * @param ParamFetcher $paramFetcher
     */
    public function aaa(ParamFetcher $paramFetcher)
    {
    }
}

The computed swagger file:

{"swagger":"2.0","info":{"title":"My App","description":"This is an awesome app!","version":"1.0.0"},"paths":{"\/api\/rewards":{"get":{"parameters":[{"name":"page","in":"query","allowEmptyValue":false,"required":false,"description":"Page of the overview.","type":"string","format":"\\d+","default":"1"}],"responses":{"default":{"description":""}}}},"\/api\/doc.json":{"get":{"responses":{"default":{"description":""}}}}}}