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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_invalid_content_type.json

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_jwt_security.json

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_laravel_security.json

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_pdf.json

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_plain_text.json

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

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_roles_request_without_info.json

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

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

tests/fixtures/SwaggerServiceTest/tmp_data_search_users_request.json

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

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