Merge pull request #366 from shalvah/v3

Improvements to parsing @bodyParam

Author: shalvah

.gitattributes

@@ -7,3 +7,4 @@
 /.travis.yml export-ignore
 /phpunit.xml export-ignore
 /README.md export-ignore
+/body-params.png export-ignore

README.md

@@ -180,7 +180,7 @@ public function createPost()
 
 They will be included in the generated documentation text and example requests.
 
-**Result:** ![Form Request](http://marcelpociot.de/documentarian/form_request.png)
+**Result:** ![](body-params.png)
 
 ### Providing an example response
 You can provide an example response for a route. This will be disaplyed in the examples section. There are several ways of doing this.

body-params.png

@@ -13,13 +13,13 @@
 curl -X {{$parsedRoute['methods'][0]}} {{$parsedRoute['methods'][0] == 'GET' ? '-G ' : ''}}"{{ trim(config('app.docs_url') ?: config('app.url'), '/')}}/{{ ltrim($parsedRoute['uri'], '/') }}" \
     -H "Accept: application/json"@if(count($parsedRoute['headers'])) \
 @foreach($parsedRoute['headers'] as $header => $value)
-    -H "{{$header}}"="{{$value}}" @if(! ($loop->last))\
+    -H "{{$header}}: {{$value}}" @if(! ($loop->last))\
     @endif
 @endforeach
 @endif
 @if(count($parsedRoute['parameters'])) \
 @foreach($parsedRoute['parameters'] as $attribute => $parameter)
-    -d "{{$attribute}}"="{{$parameter['value']}}" @if(! ($loop->last))\
+    -d "{{$attribute}}"={{$parameter['value']}} @if(! ($loop->last))\
     @endif
 @endforeach
 @endif
@@ -71,7 +71,7 @@
 Parameter | Type | Status | Description
 --------- | ------- | ------- | ------- | -----------
 @foreach($parsedRoute['parameters'] as $attribute => $parameter)
-    {{$attribute}} | {{$parameter['type']}} | @if($parameter['required']) required @else optional @endif | {!! implode(' ',$parameter['description']) !!}
+    {{$attribute}} | {{$parameter['type']}} | @if($parameter['required']) required @else optional @endif | {!! $parameter['description'] !!}
 @endforeach
 @endif
 

resources/views/partials/route.blade.php

@@ -2,6 +2,7 @@
 
 namespace Mpociot\ApiDoc\Generators;
 
+use Faker\Factory;
 use ReflectionClass;
 use Illuminate\Support\Str;
 use League\Fractal\Manager;
@@ -110,12 +111,26 @@ protected function getParametersFromDocBlock($tags)
                 return $tag instanceof Tag && $tag->getName() === 'bodyParam';
             })
             ->mapWithKeys(function ($tag) {
-                preg_match('/(.+?)\s+(.+?)\s+(required\s+)?(.+)/', $tag->getContent(), $content);
-                list($_, $name, $type, $required, $description) = $content;
-                $required = trim($required) == 'required' ? true : false;
+                preg_match('/(.+?)\s+(.+?)\s+(required\s+)?(.*)/', $tag->getContent(), $content);
+                if (empty($content)) {
+                    // this means only name and type were supplied
+                    list($name, $type) = preg_split('/\s+/', $tag->getContent());
+                    $required = false;
+                    $description = '';
+                } else {
+                    list($_, $name, $type, $required, $description) = $content;
+                    $description = trim($description);
+                    if ($description == 'required' && empty(trim($required))) {
+                        $required = $description;
+                        $description = '';
+                    }
+                    $required = trim($required) == 'required' ? true : false;
+                }
+
                 $type = $this->normalizeParameterType($type);
+                $value = $this->generateDummyValue($type);
 
-                return [$name => compact('type', 'description', 'required')];
+                return [$name => compact('type', 'description', 'required', 'value')];
             })->toArray();
 
         return $parameters;
@@ -382,8 +397,39 @@ private function normalizeParameterType($type)
         $typeMap = [
             'int' => 'integer',
             'bool' => 'boolean',
+            'double' => 'float',
         ];
 
         return $type ? ($typeMap[$type] ?? $type) : 'string';
     }
+
+    private function generateDummyValue(string $type)
+    {
+        $faker = Factory::create();
+        $fakes = [
+            'integer' => function () {
+                return rand(1, 20);
+            },
+            'number' => function () use ($faker) {
+                return $faker->randomFloat();
+            },
+            'float' => function () use ($faker) {
+                return $faker->randomFloat();
+            },
+            'boolean' => function () use ($faker) {
+                return $faker->boolean();
+            },
+            'string' => function () use ($faker) {
+                return str_random();
+            },
+            'array' => function () {
+                return '[]';
+            },
+            'object' => function () {
+                return '{}';
+            },
+        ];
+
+        return $fakes[$type]() ?? $fakes['string']();
+    }
 }

src/Generators/AbstractGenerator.php

@@ -25,6 +25,10 @@ public function withEndpointDescription()
     /**
      * @bodyParam user_id int required The id of the user.
      * @bodyParam room_id string The id of the room.
+     * @bodyParam forever boolean Whether to ban the user forever.
+     * @bodyParam another_one number Just need something here.
+     * @bodyParam yet_another_param object required
+     * @bodyParam even_more_param array
      */
     public function withBodyParameters()
     {

tests/Fixtures/TestController.php

@@ -21,7 +21,7 @@ Welcome to the generated API reference.
 <!-- END_INFO -->
 
 #general
-<!-- START_0bef4e738c9d6720ad43b062015d1078 -->
+<!-- START_264ee15c728df32e7ca6eedce5e42dcb -->
 ## Example title.
 
 This will be the long description.
@@ -30,18 +30,22 @@ It can also be multiple lines long.
 > Example request:
 
 ```bash
-curl -X GET -G "http://localhost/api/test" \
-    -H "Accept: application/json"
+curl -X GET -G "http://localhost/api/withDescription" \
+    -H "Accept: application/json" \
+    -H "Authorization: customAuthToken" \
+        -H "Custom-Header: NotSoCustom" 
 ```
 
 ```javascript
 var settings = {
     "async": true,
     "crossDomain": true,
-    "url": "http://localhost/api/test",
+    "url": "http://localhost/api/withDescription",
     "method": "GET",
     "headers": {
         "accept": "application/json",
+        "Authorization": "customAuthToken",
+        "Custom-Header": "NotSoCustom",
     }
 }
 
@@ -57,29 +61,33 @@ null
 ```
 
 ### HTTP Request
-`GET api/test`
+`GET api/withDescription`
 
 
-<!-- END_0bef4e738c9d6720ad43b062015d1078 -->
+<!-- END_264ee15c728df32e7ca6eedce5e42dcb -->
 
-<!-- START_39a6bfda1d6a0c4a5447f51b62557456 -->
-## api/responseTag
+<!-- START_9cedd363be06f5512f9e844b100fcc9d -->
+## api/withResponseTag
 
 > Example request:
 
 ```bash
-curl -X GET -G "http://localhost/api/responseTag" \
-    -H "Accept: application/json"
+curl -X GET -G "http://localhost/api/withResponseTag" \
+    -H "Accept: application/json" \
+    -H "Authorization: customAuthToken" \
+        -H "Custom-Header: NotSoCustom" 
 ```
 
 ```javascript
 var settings = {
     "async": true,
     "crossDomain": true,
-    "url": "http://localhost/api/responseTag",
+    "url": "http://localhost/api/withResponseTag",
     "method": "GET",
     "headers": {
         "accept": "application/json",
+        "Authorization": "customAuthToken",
+        "Custom-Header": "NotSoCustom",
     }
 }
 
@@ -101,9 +109,75 @@ $.ajax(settings).done(function (response) {
 ```
 
 ### HTTP Request
-`GET api/responseTag`
+`GET api/withResponseTag`
 
 
-<!-- END_39a6bfda1d6a0c4a5447f51b62557456 -->
+<!-- END_9cedd363be06f5512f9e844b100fcc9d -->
+
+<!-- START_a25cb3b490fa579d7d77b386bbb7ec03 -->
+## api/withBodyParameters
+
+> Example request:
+
+```bash
+curl -X GET -G "http://localhost/api/withBodyParameters" \
+    -H "Accept: application/json" \
+    -H "Authorization: customAuthToken" \
+        -H "Custom-Header: NotSoCustom"  \
+    -d "user_id"=14 \
+        -d "room_id"=KHEnlMeSksAYgNtw \
+        -d "forever"=1 \
+        -d "another_one"=4919.5 \
+        -d "yet_another_param"={} \
+        -d "even_more_param"=[] 
+```
+
+```javascript
+var settings = {
+    "async": true,
+    "crossDomain": true,
+    "url": "http://localhost/api/withBodyParameters",
+    "method": "GET",
+    "data": {
+        "user_id": 14,
+        "room_id": "KHEnlMeSksAYgNtw",
+        "forever": true,
+        "another_one": 4919.5,
+        "yet_another_param": "{}",
+        "even_more_param": "[]"
+    },
+    "headers": {
+        "accept": "application/json",
+        "Authorization": "customAuthToken",
+        "Custom-Header": "NotSoCustom",
+    }
+}
+
+$.ajax(settings).done(function (response) {
+    console.log(response);
+});
+```
+
+> Example response:
+
+```json
+null
+```
+
+### HTTP Request
+`GET api/withBodyParameters`
+
+#### Parameters
+
+Parameter | Type | Status | Description
+--------- | ------- | ------- | ------- | -----------
+    user_id | integer |  required  | The id of the user.
+    room_id | string |  optional  | The id of the room.
+    forever | boolean |  optional  | Whether to ban the user forever.
+    another_one | number |  optional  | Just need something here.
+    yet_another_param | object |  required  | 
+    even_more_param | array |  optional  | 
+
+<!-- END_a25cb3b490fa579d7d77b386bbb7ec03 -->
 
 

tests/Fixtures/index.md

@@ -155,10 +155,19 @@ public function can_parse_partial_resource_routes()
     /** @test */
     public function generated_markdown_file_is_correct()
     {
-        RouteFacade::get('/api/test', TestController::class.'@withEndpointDescription');
-        RouteFacade::get('/api/responseTag', TestController::class.'@withResponseTag');
+        $this->markTestSkipped('Test is non-deterministic since example values for body parameters are random.');
+
+        RouteFacade::get('/api/withDescription', TestController::class.'@withEndpointDescription');
+        RouteFacade::get('/api/withResponseTag', TestController::class.'@withResponseTag');
+        RouteFacade::get('/api/withBodyParameters', TestController::class.'@withBodyParameters');
 
         config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        config([
+            'apidoc.routes.0.apply.headers' => [
+                'Authorization' => 'customAuthToken',
+                'Custom-Header' => 'NotSoCustom',
+            ],
+        ]);
         $this->artisan('apidoc:generate');
 
         $generatedMarkdown = __DIR__.'/../public/docs/source/index.md';

tests/GenerateDocumentationTest.php

@@ -57,6 +57,26 @@ public function test_can_parse_body_parameters()
                 'required' => false,
                 'description' => 'The id of the room.',
             ],
+            'forever' => [
+                'type' => 'boolean',
+                'required' => false,
+                'description' => 'Whether to ban the user forever.',
+            ],
+            'another_one' => [
+                'type' => 'number',
+                'required' => false,
+                'description' => 'Just need something here.',
+            ],
+            'yet_another_param' => [
+                'type' => 'object',
+                'required' => true,
+                'description' => '',
+            ],
+            'even_more_param' => [
+                'type' => 'array',
+                'required' => false,
+                'description' => '',
+            ],
         ], $parameters);
     }