From 05b79ca89e097985bf15aeecd927c7b53aebd095 Mon Sep 17 00:00:00 2001
From: Kris <git@k118.de>
Date: Sat, 30 Nov 2024 17:15:46 +0100
Subject: [PATCH] :memo: add `year-in-review` endpoint to documentation (#3012)

---
 .env.example                                  |  3 +--
 .../API/v1/YearInReviewController.php         | 22 ++++++++++++++-----
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/.env.example b/.env.example
index 09203efc0..75261c04c 100644
--- a/.env.example
+++ b/.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
diff --git a/app/Http/Controllers/API/v1/YearInReviewController.php b/app/Http/Controllers/API/v1/YearInReviewController.php
index ca2d42ad7..ed1b06b76 100644
--- a/app/Http/Controllers/API/v1/YearInReviewController.php
+++ b/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) {