Merge pull request #72 from evillemez/apidoc_return

Updated README, added `return` to html output

Formatter/MarkdownFormatter.php

@@ -76,6 +76,7 @@ class MarkdownFormatter extends AbstractFormatter
                 $markdown .= sprintf("%s:\n\n", $name);
                 $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
                 $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+                $markdown .= sprintf("  * readonly: %s\n", $parameter['readonly'] ? 'true' : 'false');
 
                 if (isset($parameter['description']) && !empty($parameter['description'])) {
                     $markdown .= sprintf("  * description: %s\n", $parameter['description']);
@@ -92,6 +93,7 @@ class MarkdownFormatter extends AbstractFormatter
                 $markdown .= sprintf("%s:\n\n", $name);
                 $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
                 $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+                $markdown .= sprintf("  * readonly: %s\n", $parameter['readonly'] ? 'true' : 'false');
 
                 if (isset($parameter['description']) && !empty($parameter['description'])) {
                     $markdown .= sprintf("  * description: %s\n", $parameter['description']);

README.md

@@ -83,6 +83,7 @@ class YourController extends Controller
      * @ApiDoc(
      *  description="Create a new Object",
      *  input="Your\Namespace\Form\Type\YourType"
+     *  return='Your\Namespace\Class'
      * )
      */
     public function postAction()
@@ -101,6 +102,8 @@ The following properties are available:
 
 * `input`: the input type associated to the method, currently this supports Form Types, and classes with JMS Serializer
  metadata, useful for POST|PUT methods, either as FQCN or as form type (if it is registered in the form factory in the container)
+ 
+* `return`: the return type associated with the response.  Specified and parsed the same way as `input`.
 
 Each _filter_ has to define a `name` parameter, but other parameters are free. Filters are often optional
 parameters, and you can document them as you want, but keep in mind to be consistent for the whole documentation.

Resources/views/method.html.twig

@@ -91,15 +91,40 @@
                             <th>Parameter</th>
                             <th>Type</th>
                             <th>Required?</th>
+                            <th>Read Only?</th>
                             <th>Description</th>
                         </tr>
                     </thead>
                     <tbody>
                         {% for name, infos in data.parameters %}
+                            {% if not infos.readonly %}
+                                <tr>
+                                    <td>{{ name }}</td>
+                                    <td>{{ infos.dataType }}</td>
+                                    <td>{{ infos.required ? 'true' : 'false' }}</td>
+                                    <td>{{ infos.description }}</td>
+                                </tr>
+                            {% endif %}
+                        {% endfor %}
+                    </tbody>
+                </table>
+            {% endif %}
+
+            {% if data.response is defined and data.response is not empty %}
+                <h4>Return</h4>
+                <table class='fullwidth'>
+                    <thead>
+                        <tr>
+                            <th>Parameter</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {% for name, infos in data.response %}
                             <tr>
                                 <td>{{ name }}</td>
                                 <td>{{ infos.dataType }}</td>
-                                <td>{{ infos.required ? 'true' : 'false' }}</td>
                                 <td>{{ infos.description }}</td>
                             </tr>
                         {% endfor %}

Tests/Formatter/MarkdownFormatterTest.php

@@ -83,17 +83,20 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 b:
 
   * type: string
   * required: false
+  * readonly: false
 
 c:
 
   * type: boolean
   * required: true
+  * readonly: false
 
 
 ### `POST` /tests.{_format} ###
@@ -111,17 +114,20 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 b:
 
   * type: string
   * required: false
+  * readonly: false
 
 c:
 
   * type: boolean
   * required: true
+  * readonly: false
 
 
 
@@ -137,6 +143,7 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description
 
 
@@ -165,36 +172,42 @@ foo:
 
   * type: string
   * required: false
+  * readonly: false
   * description: No description.
 
 bar:
 
   * type: DateTime
   * required: false
+  * readonly: true
   * description: No description.
 
 number:
 
   * type: double
   * required: false
+  * readonly: false
   * description: No description.
 
 arr:
 
   * type: array
   * required: false
+  * readonly: false
   * description: No description.
 
 nested:
 
   * type: object (JmsNested)
   * required: false
+  * readonly: false
   * description: No description.
 
 nestedArray:
 
   * type: array of objects (JmsNested)
   * required: false
+  * readonly: false
   * description: No description.
 
 
@@ -208,6 +221,7 @@ a:
 
   * type: string
   * required: true
+  * readonly: false
   * description: A nice description