From f0394fc1f35d82dc4a8a3e19970bca97bba40304 Mon Sep 17 00:00:00 2001 From: Ernestas Staugaitis Date: Tue, 19 May 2020 00:06:34 +0300 Subject: [PATCH 1/4] form-data support --- src/Writing/PostmanCollectionWriter.php | 50 ++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php index fa6d3fc1..3f8b8615 100644 --- a/src/Writing/PostmanCollectionWriter.php +++ b/src/Writing/PostmanCollectionWriter.php @@ -71,8 +71,6 @@ public function makePostmanCollection() protected function generateEndpointItem($route) { - $mode = 'raw'; - $method = $route['methods'][0]; return [ @@ -81,16 +79,56 @@ protected function generateEndpointItem($route) 'url' => $this->makeUrlData($route), 'method' => $method, 'header' => $this->resolveHeadersForRoute($route), - 'body' => [ - 'mode' => $mode, - $mode => json_encode($route['cleanBodyParameters'], JSON_PRETTY_PRINT), - ], + 'body' => $this->getBodyOptions($route), 'description' => $route['metadata']['description'] ?? null, 'response' => [], ], ]; } + protected function getBodyOptions($route) + { + + $body = []; + $contentType = $route['headers']['Content-Type']; + switch ($contentType) { + case 'multipart/form-data': + $mode = 'formdata'; + break; + case 'application/json': + case 'default': + $mode = 'raw'; + } + $body['mode'] = $mode; + + switch ($mode) { + case 'formdata': + foreach ($route['cleanBodyParameters'] as $key => $value) { + $params = [ + 'key' => $key, + 'value' => $value, + 'type' => 'text' + ]; + $body[$mode][] = $params; + } + foreach ($route['fileParameters'] as $key => $value) { + $params = [ + 'key' => $key, + 'src' => [], + 'type' => 'file' + ]; + $body[$mode][] = $params; + } + break; + case 'raw': + case 'default': + $body[$mode] = json_encode($route['cleanBodyParameters'], JSON_PRETTY_PRINT); + $body['options'][$mode]['language'] = 'json'; + } + return $body; + } + + protected function resolveHeadersForRoute($route) { $headers = collect($route['headers']); From 6693737b489e422cda2517c98e3f211c0846bc6c Mon Sep 17 00:00:00 2001 From: Ernestas Staugaitis Date: Tue, 19 May 2020 00:16:16 +0300 Subject: [PATCH 2/4] form-data support --- src/Writing/PostmanCollectionWriter.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php index 3f8b8615..dfab4174 100644 --- a/src/Writing/PostmanCollectionWriter.php +++ b/src/Writing/PostmanCollectionWriter.php @@ -69,24 +69,24 @@ public function makePostmanCollection() return json_encode($collection, JSON_PRETTY_PRINT); } - protected function generateEndpointItem($route) + protected function generateEndpointItem($route): array { $method = $route['methods'][0]; return [ - 'name' => $route['metadata']['title'] != '' ? $route['metadata']['title'] : $route['uri'], + 'name' => $route['metadata']['title'] !== '' ? $route['metadata']['title'] : $route['uri'], 'request' => [ 'url' => $this->makeUrlData($route), 'method' => $method, 'header' => $this->resolveHeadersForRoute($route), - 'body' => $this->getBodyOptions($route), + 'body' => $this->getBodyData($route), 'description' => $route['metadata']['description'] ?? null, 'response' => [], ], ]; } - protected function getBodyOptions($route) + protected function getBodyData($route): array { $body = []; From 52020bbb3407709d0529e4386f410866e16d241b Mon Sep 17 00:00:00 2001 From: Ernestas Staugaitis Date: Tue, 19 May 2020 01:46:48 +0300 Subject: [PATCH 3/4] added unit test, increased timeout --- composer.json | 3 +- src/Writing/PostmanCollectionWriter.php | 6 +- tests/Fixtures/TestController.php | 11 ++++ tests/Fixtures/collection.json | 63 ++++++++++++++++--- tests/Fixtures/collection_custom_url.json | 14 ++++- .../collection_with_body_parameters.json | 7 ++- .../collection_with_custom_headers.json | 7 ++- .../collection_with_form_data_parameters.json | 56 +++++++++++++++++ .../collection_with_query_parameters.json | 7 ++- .../Fixtures/collection_with_secure_url.json | 14 ++++- tests/GenerateDocumentationTest.php | 16 +++++ 11 files changed, 184 insertions(+), 20 deletions(-) create mode 100644 tests/Fixtures/collection_with_form_data_parameters.json diff --git a/composer.json b/composer.json index b9d824a9..6b60bff4 100644 --- a/composer.json +++ b/composer.json @@ -67,7 +67,8 @@ }, "config": { "preferred-install": "dist", - "sort-packages": true + "sort-packages": true, + "process-timeout": 600 }, "replace": { "mpociot/laravel-apidoc-generator": "*" diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php index dfab4174..2d9d9029 100644 --- a/src/Writing/PostmanCollectionWriter.php +++ b/src/Writing/PostmanCollectionWriter.php @@ -90,13 +90,13 @@ protected function getBodyData($route): array { $body = []; - $contentType = $route['headers']['Content-Type']; + $contentType = $route['headers']['Content-Type'] ?? null; switch ($contentType) { case 'multipart/form-data': $mode = 'formdata'; break; case 'application/json': - case 'default': + default: $mode = 'raw'; } $body['mode'] = $mode; @@ -121,7 +121,7 @@ protected function getBodyData($route): array } break; case 'raw': - case 'default': + default: $body[$mode] = json_encode($route['cleanBodyParameters'], JSON_PRETTY_PRINT); $body['options'][$mode]['language'] = 'json'; } diff --git a/tests/Fixtures/TestController.php b/tests/Fixtures/TestController.php index 5738a2cd..0cdc7b38 100644 --- a/tests/Fixtures/TestController.php +++ b/tests/Fixtures/TestController.php @@ -89,6 +89,17 @@ public function withBodyParameters() return ''; } + /** + * Endpoint with body form data parameters. + * + * @bodyParam name string required Name of image. Example: cat.jpg + * @bodyParam image file required The image. + */ + public function withFormDataParams() + { + return ''; + } + /** * Endpoint with body parameters as array. * diff --git a/tests/Fixtures/collection.json b/tests/Fixtures/collection.json index 60cc4d27..4e0043bd 100644 --- a/tests/Fixtures/collection.json +++ b/tests/Fixtures/collection.json @@ -41,7 +41,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "This will be the long description.\nIt can also be multiple lines long.", "response": [] @@ -77,7 +82,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -113,7 +123,12 @@ ], "body": { "mode": "raw", - "raw": "{\n \"user_id\": 9,\n \"room_id\": \"consequatur\",\n \"forever\": false,\n \"another_one\": 11613.31890586,\n \"yet_another_param\": {\n \"name\": \"consequatur\"\n },\n \"even_more_param\": [\n 11613.31890586\n ],\n \"book\": {\n \"name\": \"consequatur\",\n \"author_id\": 17,\n \"pages_count\": 17\n },\n \"ids\": [\n 17\n ],\n \"users\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }\n ]\n}" + "raw": "{\n \"user_id\": 9,\n \"room_id\": \"consequatur\",\n \"forever\": false,\n \"another_one\": 11613.31890586,\n \"yet_another_param\": {\n \"name\": \"consequatur\"\n },\n \"even_more_param\": [\n 11613.31890586\n ],\n \"book\": {\n \"name\": \"consequatur\",\n \"author_id\": 17,\n \"pages_count\": 17\n },\n \"ids\": [\n 17\n ],\n \"users\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -180,7 +195,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -216,7 +236,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -252,7 +277,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -288,7 +318,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -330,7 +365,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] @@ -387,7 +427,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/Fixtures/collection_custom_url.json b/tests/Fixtures/collection_custom_url.json index 2938a4bf..69446e22 100644 --- a/tests/Fixtures/collection_custom_url.json +++ b/tests/Fixtures/collection_custom_url.json @@ -33,7 +33,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "This will be the long description.\nIt can also be multiple lines long.", "response": [] @@ -61,7 +66,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/Fixtures/collection_with_body_parameters.json b/tests/Fixtures/collection_with_body_parameters.json index 35ad5a18..d4b1158f 100644 --- a/tests/Fixtures/collection_with_body_parameters.json +++ b/tests/Fixtures/collection_with_body_parameters.json @@ -33,7 +33,12 @@ ], "body": { "mode": "raw", - "raw": "{\n \"user_id\": 9,\n \"room_id\": \"consequatur\",\n \"forever\": false,\n \"another_one\": 11613.31890586,\n \"yet_another_param\": {\n \"name\": \"consequatur\"\n },\n \"even_more_param\": [\n 11613.31890586\n ],\n \"book\": {\n \"name\": \"consequatur\",\n \"author_id\": 17,\n \"pages_count\": 17\n },\n \"ids\": [\n 17\n ],\n \"users\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }\n ]\n}" + "raw": "{\n \"user_id\": 9,\n \"room_id\": \"consequatur\",\n \"forever\": false,\n \"another_one\": 11613.31890586,\n \"yet_another_param\": {\n \"name\": \"consequatur\"\n },\n \"even_more_param\": [\n 11613.31890586\n ],\n \"book\": {\n \"name\": \"consequatur\",\n \"author_id\": 17,\n \"pages_count\": 17\n },\n \"ids\": [\n 17\n ],\n \"users\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/Fixtures/collection_with_custom_headers.json b/tests/Fixtures/collection_with_custom_headers.json index ac79279b..8c770147 100644 --- a/tests/Fixtures/collection_with_custom_headers.json +++ b/tests/Fixtures/collection_with_custom_headers.json @@ -37,7 +37,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/Fixtures/collection_with_form_data_parameters.json b/tests/Fixtures/collection_with_form_data_parameters.json new file mode 100644 index 00000000..e5595a01 --- /dev/null +++ b/tests/Fixtures/collection_with_form_data_parameters.json @@ -0,0 +1,56 @@ +{ + "variables": [], + "info": { + "name": "Laravel API", + "_postman_id": "", + "description": "", + "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json" + }, + "item": [ + { + "name": "Group A", + "description": "", + "item": [ + { + "name": "Endpoint with body form data parameters.", + "request": { + "url": { + "protocol": "http", + "host": "localhost", + "path": "api\/withFormDataParams", + "query": [] + }, + "method": "GET", + "header": [ + { + "key": "Content-Type", + "value": "multipart\/form-data" + }, + { + "key": "Accept", + "value": "application\/json" + } + ], + "body": { + "mode": "formdata", + "formdata": [ + { + "key": "name", + "value": "cat.jpg", + "type": "text" + }, + { + "key": "image", + "src": [], + "type": "file" + } + ] + }, + "description": "", + "response": [] + } + } + ] + } + ] +} diff --git a/tests/Fixtures/collection_with_query_parameters.json b/tests/Fixtures/collection_with_query_parameters.json index a04043e6..2510e5e1 100644 --- a/tests/Fixtures/collection_with_query_parameters.json +++ b/tests/Fixtures/collection_with_query_parameters.json @@ -64,7 +64,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/Fixtures/collection_with_secure_url.json b/tests/Fixtures/collection_with_secure_url.json index e6918665..4b79cef5 100644 --- a/tests/Fixtures/collection_with_secure_url.json +++ b/tests/Fixtures/collection_with_secure_url.json @@ -33,7 +33,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "This will be the long description.\nIt can also be multiple lines long.", "response": [] @@ -61,7 +66,12 @@ ], "body": { "mode": "raw", - "raw": "[]" + "raw": "[]", + "options": { + "raw": { + "language": "json" + } + } }, "description": "", "response": [] diff --git a/tests/GenerateDocumentationTest.php b/tests/GenerateDocumentationTest.php index ec96fa24..9de550d7 100644 --- a/tests/GenerateDocumentationTest.php +++ b/tests/GenerateDocumentationTest.php @@ -347,6 +347,22 @@ public function generated_postman_collection_can_add_body_parameters() $this->assertEquals($fixtureCollection, $generatedCollection); } + /** @test */ + public function generated_postman_collection_can_add_form_data_parameters() + { + RouteFacade::get('/api/withFormDataParams', TestController::class . '@withFormDataParams'); + // We want to have the same values for params each time + config(['scribe.faker_seed' => 1234]); + config(['scribe.routes.0.match.prefixes' => ['api/*']]); + $this->artisan('scribe:generate'); + + $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true); + // The Postman ID varies from call to call; erase it to make the test data reproducible. + $generatedCollection['info']['_postman_id'] = ''; + $fixtureCollection = json_decode(file_get_contents(__DIR__ . '/Fixtures/collection_with_form_data_parameters.json'), true); + $this->assertEquals($fixtureCollection, $generatedCollection); + } + /** @test */ public function can_append_custom_http_headers() { From 0309886f0c3505b55b2c43fd4b9cf35785cf7c82 Mon Sep 17 00:00:00 2001 From: Ernestas Staugaitis Date: Wed, 20 May 2020 01:21:02 +0300 Subject: [PATCH 4/4] Update src/Writing/PostmanCollectionWriter.php Co-authored-by: Shalvah --- src/Writing/PostmanCollectionWriter.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php index 2d9d9029..f34fb714 100644 --- a/src/Writing/PostmanCollectionWriter.php +++ b/src/Writing/PostmanCollectionWriter.php @@ -86,7 +86,7 @@ protected function generateEndpointItem($route): array ]; } - protected function getBodyData($route): array + protected function getBodyData(array $route): array { $body = [];