📝 add year-in-review endpoint to documentation (#3012)

.env.example

@@ -9,8 +9,6 @@ FORCE_HTTPS=false
 
 LOG_LEVEL=debug # You can change this to info, warning or error for production use
 
-L5_SWAGGER_CONST_HOST=http://localhost:8000
-
 # Change this according to your database configuration
 # To use SQLite, have a look here: https://laravel.com/docs/10.x/database#sqlite-configuration
 DB_CONNECTION=mysql
@@ -88,3 +86,4 @@ PRIVACY_ACCOUNT_DELETION_DELETE_ACCOUNT=false
 # This will make sure that the documentation is always up to date, if you access it via /api/documentation.
 # So you don't forget to publish the documentation after changing the API.
 L5_SWAGGER_GENERATE_ALWAYS=true
+L5_SWAGGER_CONST_HOST=http://localhost:8000

app/Http/Controllers/API/v1/YearInReviewController.php

@@ -11,11 +11,23 @@ class YearInReviewController extends Controller
 {
 
     /**
-     * Returns the year in review for the given year and authenticated user
-     *
-     * @param Request $request with token and year
-     *
-     * @return JsonResponse
+     * @OA\Get(
+     *      path="/year-in-review",
+     *      operationId="getYearInReview",
+     *      tags={"Statistics"},
+     *      summary="Returns the year in review for the given year and authenticated user",
+     *      description="Please note: This endpoint is only available when the year in review feature is enabled in the backend configuration. There is no full documentation - this endpoint may change every year.",
+     *      @OA\Response(
+     *          response=200,
+     *          description="JSON object with the year in review data. The structure of the object may change every year. There is no full documentation at this point.",
+     *       ),
+     *       @OA\Response(response=400, description="Bad request"),
+     *       @OA\Response(response=401, description="Unauthorized"),
+     *       @OA\Response(response=403, description="Year in review is not active"),
+     *       security={
+     *          {"passport": {"create-statuses"}}, {"token": {}}
+     *       }
+     *     )
      */
     public function show(Request $request): JsonResponse {
         if (config('trwl.year_in_review.backend') === false) {