Merge pull request #114 from RonasIT/102-add-ability-to-mark-routes-as-deprecated

feat: add ability to mark routes as deprecated.

Author: DenTray

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***
 > 

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;
             }
         }

tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json

@@ -71,7 +71,8 @@
         },
         "security": [],
         "description": "",
-        "summary": "test"
+        "summary": "test",
+        "deprecated": false
       }
     }
   },

tests/fixtures/SwaggerServiceTest/tmp_data_create_user_request.json

@@ -39,7 +39,8 @@
         },
         "security": [],
         "description": "",
-        "summary": "test"
+        "summary": "test",
+        "deprecated": false
       }
     }
   },

tests/fixtures/SwaggerServiceTest/tmp_data_get_user_request.json

@@ -66,7 +66,8 @@
                 },
                 "security": [],
                 "description": "",
-                "summary": "test"
+                "summary": "test",
+                "deprecated": false
             }
         }
     },

tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request.json

@@ -65,7 +65,8 @@
           }
         ],
         "description": "",
-        "summary": "test"
+        "summary": "test",
+        "deprecated": false
       }
     }
   },

tests/fixtures/SwaggerServiceTest/tmp_data_post_user_request_with_object_params.json

@@ -63,7 +63,8 @@
           }
         ],
         "description": "",
-        "summary": "test"
+        "summary": "test",
+        "deprecated": false
       }
     }
   },

tests/fixtures/SwaggerServiceTest/tmp_data_put_user_request.json

@@ -70,7 +70,8 @@
           }
         ],
         "description": "",
-        "summary": "test"
+        "summary": "test",
+        "deprecated": false
       }
     }
   },

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
       }
     }
   },

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request.json

@@ -71,7 +71,8 @@
                 },
                 "security": [],
                 "description": "",
-                "summary": "test"
+                "summary": "test",
+                "deprecated": false
             }
         }
     },