From 0d7c2272bc1062a91cab2e87d8fc47206fbd7850 Mon Sep 17 00:00:00 2001 From: Evan Villemez 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 @@ Parameter Type Required? + Read Only? Description @@ -100,6 +101,33 @@ {{ name }} {{ infos.dataType }} {{ infos.required ? 'true' : 'false' }} + {{ infos.readonly }} ? 'true' : 'false' + {{ infos.description }} + + {% endfor %} + + + {% endif %} + + {% if data.response is defined and data.response is not empty %} +

Return

+ + + + + + + + + + + + {% for name, infos in data.response %} + + + + + {% 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 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 @@ - + {% endfor %} @@ -127,7 +127,7 @@ - + {% endfor %} From 94a3d5858fdd3ffceeaa2e4edcf735b972ef9ab2 Mon Sep 17 00:00:00 2001 From: Evan Villemez 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 @@ - - @@ -126,8 +124,6 @@ - - {% endfor %} From da1116a43a83a4c1454310a9f0faa234c0806659 Mon Sep 17 00:00:00 2001 From: Evan Villemez 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 @@ {% for name, infos in data.parameters %} - - - - - - - + {% if not infos.readonly %} + + + + + + + {% endif %} {% endfor %}
ParameterTypeRequired?Read Only?Description
{{ name }}{{ infos.dataType }}{{ infos.required ? 'true' : 'false' }}{{ infos.readonly }} ? 'true' : 'false' {{ infos.description }}
{{ name }} {{ infos.dataType }} {{ infos.required ? 'true' : 'false' }}{{ infos.readonly }} ? 'true' : 'false'{{ infos.readonly ? 'true' : 'false' }} {{ infos.description }}
{{ name }} {{ infos.dataType }} {{ infos.required ? 'true' : 'false' }}{{ infos.readonly }} ? 'true' : 'false'{{ infos.readonly ? 'true' : 'false' }} {{ infos.description }}
Parameter TypeRequired?Read Only? Description
{{ name }} {{ infos.dataType }}{{ infos.required ? 'true' : 'false' }}{{ infos.readonly ? 'true' : 'false' }} {{ infos.description }}
{{ name }}{{ infos.dataType }}{{ infos.required ? 'true' : 'false' }}{{ infos.readonly ? 'true' : 'false' }}{{ infos.description }}
{{ name }}{{ infos.dataType }}{{ infos.required ? 'true' : 'false' }}{{ infos.description }}