From 0d7c2272bc1062a91cab2e87d8fc47206fbd7850 Mon Sep 17 00:00:00 2001
From: Evan Villemez <evan.villemez@americancouncils.org>
Date: Tue, 28 Aug 2012 16:43:47 -0400
Subject: [PATCH 1/4] updated documentation to reflect return property, updated
markdown formatter tests to reflect parameter readonly property
---
Formatter/MarkdownFormatter.php | 2 ++
README.md | 3 +++
Resources/views/method.html.twig | 28 +++++++++++++++++++++++
Tests/Formatter/MarkdownFormatterTest.php | 14 ++++++++++++
4 files changed, 47 insertions(+)
diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index 3126909..46a030c 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/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']);
diff --git a/README.md b/README.md
index f669443..f7f044f 100644
--- a/README.md
+++ b/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.
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index f7a1182..aab13ad 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -91,6 +91,7 @@
<th>Parameter</th>
<th>Type</th>
<th>Required?</th>
+ <th>Read Only?</th>
<th>Description</th>
</tr>
</thead>
@@ -100,6 +101,33 @@
<td>{{ name }}</td>
<td>{{ infos.dataType }}</td>
<td>{{ infos.required ? 'true' : 'false' }}</td>
+ <td>{{ infos.readonly }} ? 'true' : 'false'</td>
+ <td>{{ infos.description }}</td>
+ </tr>
+ {% 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>Required?</th>
+ <th>Read Only?</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.readonly }} ? 'true' : 'false'</td>
<td>{{ infos.description }}</td>
</tr>
{% endfor %}
diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php
index fc25e6b..dc8c6af 100644
--- a/Tests/Formatter/MarkdownFormatterTest.php
+++ b/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
From ebba238f1c290f13ea378cd3c97c11cccfe43b9b Mon Sep 17 00:00:00 2001
From: Evan Villemez <evan.villemez@americancouncils.org>
Date: Wed, 29 Aug 2012 13:30:08 -0400
Subject: [PATCH 2/4] fixed method template
---
Resources/views/method.html.twig | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index aab13ad..dc1d3b9 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -101,7 +101,7 @@
<td>{{ name }}</td>
<td>{{ infos.dataType }}</td>
<td>{{ infos.required ? 'true' : 'false' }}</td>
- <td>{{ infos.readonly }} ? 'true' : 'false'</td>
+ <td>{{ infos.readonly ? 'true' : 'false' }}</td>
<td>{{ infos.description }}</td>
</tr>
{% endfor %}
@@ -127,7 +127,7 @@
<td>{{ name }}</td>
<td>{{ infos.dataType }}</td>
<td>{{ infos.required ? 'true' : 'false' }}</td>
- <td>{{ infos.readonly }} ? 'true' : 'false'</td>
+ <td>{{ infos.readonly ? 'true' : 'false' }}</td>
<td>{{ infos.description }}</td>
</tr>
{% endfor %}
From 94a3d5858fdd3ffceeaa2e4edcf735b972ef9ab2 Mon Sep 17 00:00:00 2001
From: Evan Villemez <evan.villemez@americancouncils.org>
Date: Wed, 29 Aug 2012 14:12:12 -0400
Subject: [PATCH 3/4] removed required and readonly properties from html output
when documenting return
---
Resources/views/method.html.twig | 4 ----
1 file changed, 4 deletions(-)
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index dc1d3b9..e4b0269 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -116,8 +116,6 @@
<tr>
<th>Parameter</th>
<th>Type</th>
- <th>Required?</th>
- <th>Read Only?</th>
<th>Description</th>
</tr>
</thead>
@@ -126,8 +124,6 @@
<tr>
<td>{{ name }}</td>
<td>{{ infos.dataType }}</td>
- <td>{{ infos.required ? 'true' : 'false' }}</td>
- <td>{{ infos.readonly ? 'true' : 'false' }}</td>
<td>{{ infos.description }}</td>
</tr>
{% endfor %}
From da1116a43a83a4c1454310a9f0faa234c0806659 Mon Sep 17 00:00:00 2001
From: Evan Villemez <evan.villemez@americancouncils.org>
Date: Thu, 30 Aug 2012 15:57:43 -0400
Subject: [PATCH 4/4] stopped displaying readonly input parameters in html
template
---
Resources/views/method.html.twig | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index e4b0269..8b6ee75 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -97,13 +97,14 @@
</thead>
<tbody>
{% for name, infos in data.parameters %}
- <tr>
- <td>{{ name }}</td>
- <td>{{ infos.dataType }}</td>
- <td>{{ infos.required ? 'true' : 'false' }}</td>
- <td>{{ infos.readonly ? 'true' : 'false' }}</td>
- <td>{{ infos.description }}</td>
- </tr>
+ {% 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>