From 5b59bb6e984a26f844df72600232774c8f252ce3 Mon Sep 17 00:00:00 2001 From: Konstantin Lapkovsky Date: Sat, 11 Nov 2023 14:30:38 +0400 Subject: [PATCH] feat: add ability to mark routes as deprecated. --- readme.md | 3 +++ src/Services/SwaggerService.php | 14 ++++++++++++++ .../tmp_data_search_roles_request.json | 3 ++- .../tmp_data_create_user_request.json | 3 ++- .../tmp_data_get_user_request.json | 3 ++- .../tmp_data_post_user_request.json | 3 ++- ..._data_post_user_request_with_object_params.json | 3 ++- .../tmp_data_put_user_request.json | 3 ++- ..._put_user_request_with_early_generated_doc.json | 6 ++++-- .../tmp_data_search_roles_request.json | 3 ++- ..._search_roles_request_invalid_content_type.json | 3 ++- ...tmp_data_search_roles_request_jwt_security.json | 3 ++- ...data_search_roles_request_laravel_security.json | 3 ++- .../tmp_data_search_roles_request_pdf.json | 3 ++- .../tmp_data_search_roles_request_plain_text.json | 3 ++- ...data_search_roles_request_with_annotations.json | 3 ++- ...tmp_data_search_roles_request_without_info.json | 3 ++- ...ata_search_roles_request_without_rule_type.json | 3 ++- .../tmp_data_search_users_request.json | 3 ++- tests/support/Mock/TestRequestWithAnnotations.php | 1 + 20 files changed, 54 insertions(+), 18 deletions(-) diff --git a/readme.md b/readme.md index b95bef87..6d3b0229 100644 --- a/readme.md +++ b/readme.md @@ -69,6 +69,8 @@ passing PHPUnit tests. /** * @summary Update user * + * @deprecated + * * @description * This request should be used for updating the user data * @@ -166,6 +168,7 @@ You can use the following annotations in your request classes to customize docum - **@description** - implementation notes - **@_204** - custom description of response code. You can specify any code as you want. - **@some_field** - description of the field from the rules method +- **@deprecated** - mark route as deprecated > ***Note*** > diff --git a/src/Services/SwaggerService.php b/src/Services/SwaggerService.php index 44dd46b3..c4da9e55 100755 --- a/src/Services/SwaggerService.php +++ b/src/Services/SwaggerService.php @@ -57,6 +57,10 @@ class SwaggerService 'int' => 'integer' ]; + protected $booleanAnnotations = [ + 'deprecated' + ]; + public function __construct(Container $container) { $this->openAPIValidator = app(SwaggerSpecValidator::class); @@ -267,10 +271,16 @@ protected function parseRequest() $annotations = $this->getClassAnnotations($concreteRequest); + $this->markAsDeprecated($annotations); $this->saveParameters($concreteRequest, $annotations); $this->saveDescription($concreteRequest, $annotations); } + protected function markAsDeprecated(array $annotations) + { + $this->item['deprecated'] = Arr::get($annotations, 'deprecated', false); + } + protected function parseResponse($response) { $produceList = $this->data['paths'][$this->uri][$this->method]['produces']; @@ -782,6 +792,10 @@ protected function getClassAnnotations($class): array $paramName = str_replace('@', '', array_shift($exploded)); $paramValue = implode(' ', $exploded); + if (in_array($paramName, $this->booleanAnnotations)) { + $paramValue = true; + } + $result[$paramName] = $paramValue; } } diff --git a/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json b/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json index 71b63bcb..d97b41b7 100644 --- a/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json +++ b/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json @@ -71,7 +71,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_create_user_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_create_user_request.json index 4cec9ba7..f4c84037 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_create_user_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_create_user_request.json @@ -39,7 +39,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_get_user_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_get_user_request.json index 162ef3e2..b50eb24d 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_get_user_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_get_user_request.json @@ -66,7 +66,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request.json index 294fca70..b32fb455 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request.json @@ -65,7 +65,8 @@ } ], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request_with_object_params.json b/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request_with_object_params.json index 6f8d8b55..f3ba852f 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request_with_object_params.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request_with_object_params.json @@ -63,7 +63,8 @@ } ], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request.json index 5464ac2a..3b64c970 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request.json @@ -70,7 +70,8 @@ } ], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request_with_early_generated_doc.json b/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request_with_early_generated_doc.json index 3ac279a9..25aef98a 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request_with_early_generated_doc.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request_with_early_generated_doc.json @@ -70,7 +70,8 @@ } ], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false }, "patch": { "tags": [ @@ -112,7 +113,8 @@ } ], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request.json index fa58b2c9..cd42ead4 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request.json @@ -71,7 +71,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_invalid_content_type.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_invalid_content_type.json index 4eb94f3c..f59626a4 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_invalid_content_type.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_invalid_content_type.json @@ -41,7 +41,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_jwt_security.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_jwt_security.json index 2db52ae1..5060a324 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_jwt_security.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_jwt_security.json @@ -71,7 +71,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_laravel_security.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_laravel_security.json index ca5820de..d3f3cb72 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_laravel_security.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_laravel_security.json @@ -71,7 +71,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_pdf.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_pdf.json index 739b5410..03e4c892 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_pdf.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_pdf.json @@ -46,7 +46,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_plain_text.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_plain_text.json index 54eb92b6..ebc72a64 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_plain_text.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_plain_text.json @@ -46,7 +46,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_with_annotations.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_with_annotations.json index 518a31c5..7cbad830 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_with_annotations.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_with_annotations.json @@ -59,7 +59,8 @@ }, "security": [], "description": "Description of the request class", - "summary": "Request class to validate input data" + "summary": "Request class to validate input data", + "deprecated": true } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_info.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_info.json index de712b5b..cbaa5e5a 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_info.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_info.json @@ -71,7 +71,8 @@ }, "security": [], "description": "", - "summary": "test" + "summary": "test", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_rule_type.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_rule_type.json index bb242153..4e7e5330 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_rule_type.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_rule_type.json @@ -59,7 +59,8 @@ }, "security": [], "description": "", - "summary": "test without rule type" + "summary": "test without rule type", + "deprecated": false } } }, diff --git a/tests/fixtures/SwaggerServiceTest/tmp_data_search_users_request.json b/tests/fixtures/SwaggerServiceTest/tmp_data_search_users_request.json index b82bbf1f..c3a6218a 100644 --- a/tests/fixtures/SwaggerServiceTest/tmp_data_search_users_request.json +++ b/tests/fixtures/SwaggerServiceTest/tmp_data_search_users_request.json @@ -96,7 +96,8 @@ "security": [], "description": "", "summary": "test", - "consumes": [] + "consumes": [], + "deprecated": false } } }, diff --git a/tests/support/Mock/TestRequestWithAnnotations.php b/tests/support/Mock/TestRequestWithAnnotations.php index 79bd25a6..ac56e730 100644 --- a/tests/support/Mock/TestRequestWithAnnotations.php +++ b/tests/support/Mock/TestRequestWithAnnotations.php @@ -5,6 +5,7 @@ use Illuminate\Foundation\Http\FormRequest; /** + * @deprecated * @summary Request class to validate input data * @description Description of the request class * @_200 The operation was completed successfully