Nelmioapidocbundle: [3.0] Can't describe action in controller

[knyk]

there is no way to describe what endpoint actually do. in version 2 there was description property in @ApiDoc annotation

...
* @ApiDoc(
*  resource=true,
*  description="This is a description of your API method",
...

how can it be done now?

[dbu]

version 3 integrates swagger-php. @GuilhemN looking at https://github.com/zircote/swagger-php/blob/master/docs/Getting-started.md#arrays-and-objects i would say its the @SWG\Get annotation summary attribute - but this bundles uses symfony to know the http method and route info, so SWG\Get is not used. what is the way to do the action description? the php docblock? or is there some annotation? we should update https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/doc/index.rst#using-the-bundle to contain an example for this.

[GuilhemN]

I would recommend using php docs but people can also use https://github.com/nelmio/NelmioApiDocBundle/blob/master/Annotation/Operation.php if they want to do it explicitely.

[XanderKon]

I'm sorry, guys, but simple PHPDoc comment doesn't work for me. What's wrong?

/**
  * Lists all user entities.
  *
  * @Route("/", name="api_user_index", methods={"GET"})
  * @SWG\Response(
  *     response=200,
  *     description="Success",
  * )
  * @SWG\Tag(name="Users")
  */
  public function indexAction()
  {
      $em = $this->getDoctrine()->getManager();
      return $em->getRepository('AppBundle:User')->findAll();
  }

I don't see Lists all user entities. in description at all

[GuilhemN]

Have you ran composer require phpdocumentor/reflection-docblock?

Maybe we should just require this dependency I guess all users require it manually anyway.

[XanderKon]

@GuilhemN Yes! It helped! Thank you!

[dbu]

Maybe we should just require this dependency I guess all users require it manually anyway.

yeah lets do that. i think most people do a bit of docblocks and its surprising when it just does not work without telling that something is missing.