Repository: RonasIT/laravel-swagger (php)

Issue:
Parse deprecated annotation of a request class
According to the doc https://swagger.io/docs/specification/2-0/paths-and-operations we can use the deprecated param in open api spec

What should we do:
1. mark API as deprecated if `@deprecated` annotation was added to the related form request class
2. update readme with this info

Pull request:
feat: add ability to mark routes as deprecated.
# Description

Add the ability to mark routes as deprecated.

Fixes #102

## Type of change

- [x] New feature (non-breaking change which adds functionality)
- [x] This change requires a documentation update

# Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] Any dependent changes have been merged and published in downstream modules

Patch:
diff --git a/readme.md b/readme.md
index b95bef8..6d3b022 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 44dd46b..c4da9e5 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 @@ class SwaggerService
 
         $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 @@ class SwaggerService
                 $paramName = str_replace('@', '', array_shift($exploded));
                 $paramValue = implode(' ', $exploded);
 
+                if (in_array($paramName, $this->booleanAnnotations)) {
+                    $paramValue = true;
+                }
+
                 $result[$paramName] = $paramValue;
             }
         }


Test patch:
diff --git a/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json b/tests/fixtures/AutoDocMiddlewareTest/tmp_data_search_roles_request.json
index 71b63bc..d97b41b 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 4cec9ba..f4c8403 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 162ef3e..b50eb24 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 294fca7..b32fb45 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 6f8d8b5..f3ba852 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 5464ac2..3b64c97 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 3ac279a..25aef98 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 fa58b2c..cd42ead 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 4eb94f3..f59626a 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 2db52ae..5060a32 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 ca5820d..d3f3cb7 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 739b541..03e4c89 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 54eb92b..ebc72a6 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 518a31c..7cbad83 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 de712b5..cbaa5e5 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 bb24215..4e7e533 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 b82bbf1..c3a6218 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 79bd25a..ac56e73 100644
--- a/tests/support/Mock/TestRequestWithAnnotations.php
+++ b/tests/support/Mock/TestRequestWithAnnotations.php
@@ -5,6 +5,7 @@ namespace RonasIT\Support\Tests\Support\Mock;
 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