Merge pull request #1177 from nelmio/method-annotation-doc-improve

Provide example for action summary and description

Resources/doc/index.rst

@@ -1,6 +1,6 @@
 NelmioApiDocBundle
 ==================
-
+
 The **NelmioApiDocBundle** bundle allows you to generate documentation in the
 OpenAPI (Swagger) format and provides a sandbox to interactively browse the API documentation.
 
@@ -12,7 +12,7 @@ This bundle supports _Symfony_ route requirements, PHP annotations,
 [_FOSRestBundle_](https://github.com/FriendsOfSymfony/FOSRestBundle) annotations
 and apps using [_Api-Platform_](https://github.com/api-platform/api-platform).
 
-For models, it supports the Symfony serializer and the JMS serializer.
+For models, it supports the Symfony serializer and the JMS serializer.
 
 Migrate from 2.x to 3.0
 -----------------------
@@ -21,8 +21,8 @@ Migrate from 2.x to 3.0
 
 Installation
 ------------
-
-Open a command console, enter your project directory and execute the following command to download the latest version of this bundle:
+
+Open a command console, enter your project directory and execute the following command to download the latest version of this bundle:
 
 .. code-block:: bash
 
@@ -65,7 +65,7 @@ Open a command console, enter your project directory and execute the following c
             path: /api/doc.json
             methods: GET
             defaults: { _controller: nelmio_api_doc.controller.swagger }
-
+
     As you just installed the bundle, you'll likely see routes you don't want in
     your documentation such as `/_profiler/`. To fix this, you can filter the
     routes that are documented by configuring the bundle:
@@ -79,7 +79,7 @@ Open a command console, enter your project directory and execute the following c
                     - ^/api(?!/doc$)
 
 How does this bundle work?
---------------------------
+--------------------------
 
 It generates you a swagger documentation from your symfony app thanks to
 _Describers_. Each of these _Describers_ extract infos from various sources.
@@ -88,11 +88,11 @@ routes, etc.
 
 If you configured the ``app.swagger_ui`` route above, you can browse your
 documentation at `http://example.org/api/doc`.
-
+
 Using the bundle
 ----------------
 
-You can configure global information in the bundle configuration ``documentation.info`` section (take a look at
+You can configure global information in the bundle configuration ``documentation.info`` section (take a look at
 [the Swagger specification](http://swagger.io/specification/) to know the fields
 available):
 
@@ -123,6 +123,10 @@ To document your routes, you can use the SwaggerPHP annotations and the
     class UserController
     {
         /*
+         * List the rewards of the specified user.
+         *
+         * This call takes into account all confirmed awards, but not pending or refused awards.
+         *
          * @Route("/api/{user}/rewards", methods={"GET"})
          * @SWG\Response(
          *     response=200,
@@ -146,12 +150,14 @@ To document your routes, you can use the SwaggerPHP annotations and the
         }
     }
 
+The normal PHP docblock for the controller method is used for the summary and description.
+
 Use models
 ----------
 
 As shown in the example above, the bundle provides the ``@Model`` annotation.
 When you use it, the bundle will deduce your model properties.
-
+
 It has two options:
 
 * ``type`` to specify your model's type::
@@ -165,12 +171,12 @@ It has two options:
     /**
      * @Model(type=User::class, groups={"non_sensitive_data"})
      */
-
+
 .. warning::
 
     The ``@Model`` annotation acts like a ``@Schema`` annotation. If you nest it with a ``@Schema`` annotation, the bundle will consider that
     you're documenting an array of models.
-
+
     For instance, the following example::
 
         /**
@@ -215,7 +221,7 @@ It has two options:
         public function myAction()
         {
         }
-
+
 If you're not using the JMS Serializer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -249,4 +255,4 @@ If you need more complex features, take a look at:
 .. toctree::
     :maxdepth: 1
 
-    areas
+    areas