Автоматическая генерация API doc через Аннотации или как прийти к документированию API

        require nelmio/api-doc-bundle
    

        public function registerBundles()
        {
        //...
            return array(
                // ...
                new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
            );
        }
    

        # app/config/routing.yml

        NelmioApiDocBundle:
            resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
            prefix:   /api/doc
    

        public function getIndexAction(ParamFetcher $paramFetcher)
        {
            $view = View::create();

            $result = [
                'status' => 'success',
                'data' => [
                    'someKey' => 'SomeValue'
                ]
            ];
            $view->setData(['result' => $result]);
            return $view;
        }
    

        /**
         * @Get(name="_additional_name_in_route", path="/")
         *
         * @Template(engine="twig", template="HabrApiDocBundle:Default:index.html.twig")
         *
         * @QueryParam(
         *      name="name",
         *      requirements="\w+",
         *      strict=true,
         *      nullable=false,
         *      description="Some description"
         * )
         *
         * @param ParamFetcher $paramFetcher
         * @return View
         */
        public function getIndexAction(ParamFetcher $paramFetcher)
        {
            $view = View::create();

            $result = [
                'status' => 'success',
                'data' => [
                    'someKey' => 'SomeValue'
                ]
            ];
            $view->setData(['result' => $result]);
            return $view;
        }
    

1. @Get — самый простой и быстрый способ переопределить урл роута для методов, которые отвечают только на 1 тип запроса (REST Full). Это даст нам возможность сделать postIndexAction deleteIndexAction — ну и так далее, суть поймана.
   
2. @Templating — использовать или нет, тут уже по желанию. Я предпочту использовать, например, для стандартизации ответов.
   
3. @QueryParam — первая плюшка, использование @QueryParam или @RequestParam соответственно позволит вам управлять входными данными. Например, у нас есть поле name, которое НЕ может быть пустым, должно соответствовать патерну \w+ и не менее главное — это Description, в котором можно написать, на кой оно надо взагали.
   

* @ApiDoc(
*      statusCodes={
*          200="Returned when successful",
*          403="Returned when the user is not authorized to say hello",
*          404={
*              "Returned when the user is not found",
*              "Returned when something else is not found"
*                },
*            },
*            description = "Add here some description for this method",
*           requirements = {
*                {"name"="name", "datatype"="string", "requirements"="\w+", "description" = "description for this parameter"}
*            },
*            cache=false,
*            tags = {
*                "stable" = "green",
*                "deprecated" = "#ff0000"
*            },
*            deprecated = true,
*            section = "First section"
*       )

1. @ApiDoc() — естественно мы в начале укажем к испольлзованию сам бандл,
   
2. statusCodes — назначение данного параметра видно из его названия, но он в итоге очень красиво выглядит в документации, расскажет нам, что и в каких случаях мы можем получить в качестве ответа.
   
3. description — ну тоже как бы пришел капитан, с той лишь разницей, что теперь его будет видно в документации.
   
4. requirements — сюда пишется массив Query/Request параметров с описанием их требований, что так же будет отображено в документации.
   
5. tags — теги, это просто нечто. Когда можно на каждый метод поставить какой нибудь свой тег.
   
6. deprecated — тоже приятная фича, когда можно помечать методы, которые планируется больше не использовать.
   
7. section — одно из самых полезных дополнений, позволяет объединять в группы методы, даже если они находятся в разных классах.
   

ScreenShot