Use Swagger to document a Symfony API

Mathieu Ferment on December 16, 2017

Web APIs are trending ! They are now everywhere : they fuel Javascript single-app pages with data, they allow developers to manage an elasticsea... [Read Full]
markdown guide


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


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:


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

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.


The idea behind this post was to generate a Swagger file that can then be used for multiple purposes: generate a documentation, generate an API Client, generate pre-built query samples in Postman, be used to check if API responses are valid against the definition ...

Sami is a great tool but as far as I know only handles the documentation.


Could you help me understand, how to run (get up) this project in local?

code of conduct - report abuse