From a5929ebb297c9fbe96387fc5cb1c8c6fa81de133 Mon Sep 17 00:00:00 2001
From: Alejandro Celaya <alejandrocelaya@gmail.com>
Date: Mon, 2 Jan 2023 19:58:02 +0100
Subject: [PATCH] Added swagger docs for visits summary in tags with stats

---
 docs/swagger/definitions/TagInfo.json |  9 +++++++--
 docs/swagger/paths/v2_tags_stats.json | 21 +++++++++++++++------
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/docs/swagger/definitions/TagInfo.json b/docs/swagger/definitions/TagInfo.json
index e881ce02..41de1068 100644
--- a/docs/swagger/definitions/TagInfo.json
+++ b/docs/swagger/definitions/TagInfo.json
@@ -1,5 +1,6 @@
 {
     "type": "object",
+    "required": ["tag", "shortUrlsCount", "visitsSummary", "visitsCount"],
     "properties": {
         "tag": {
             "type": "string",
@@ -9,9 +10,13 @@
             "type": "number",
             "description": "The amount of short URLs using this tag"
         },
-        "userAgent": {
+        "visitsSummary": {
+            "$ref": "./VisitsSummary.json"
+        },
+        "visitsCount": {
+            "deprecated": true,
             "type": "number",
-            "description": "The combined amount of visits received by short URLs with this tag"
+            "description": "**[DEPRECATED]** Use visitsSummary.total instead"
         }
     }
 }
diff --git a/docs/swagger/paths/v2_tags_stats.json b/docs/swagger/paths/v2_tags_stats.json
index 91771335..150cf7b3 100644
--- a/docs/swagger/paths/v2_tags_stats.json
+++ b/docs/swagger/paths/v2_tags_stats.json
@@ -45,7 +45,7 @@
             {
                 "name": "orderBy",
                 "in": "query",
-                "description": "To determine how to order the results.<br /><br />**Important!** Ordering by `shortUrlsCount` or `visitsCount` has a [known performance issue](https://github.com/shlinkio/shlink/issues/1346) which makes loading a subset of the list take as much as loading the whole list.<br />If you plan to order by any of these fields, it's worth loading the whole list with no pagination.",
+                "description": "To determine how to order the results.<br /><br />**Important!** Ordering by `shortUrlsCount`, `visits` or `nonBotVisits` has a [known performance issue](https://github.com/shlinkio/shlink/issues/1346) which makes loading a subset of the list take as much as loading the whole list.<br />If you plan to order by any of these fields, it's worth loading the whole list with no pagination.",
                 "required": false,
                 "schema": {
                     "type": "string",
@@ -54,8 +54,10 @@
                         "tag-DESC",
                         "shortUrlsCount-ASC",
                         "shortUrlsCount-DESC",
-                        "visitsCount-ASC",
-                        "visitsCount-DESC"
+                        "visits-ASC",
+                        "visits-DESC",
+                        "nonBotVisits-ASC",
+                        "nonBotVisits-DESC"
                     ]
                 }
             }
@@ -73,7 +75,6 @@
                                     "required": ["data"],
                                     "properties": {
                                         "data": {
-                                            "description": "The tag stats will be returned only if the withStats param was provided with value 'true'",
                                             "type": "array",
                                             "items": {
                                                 "$ref": "../definitions/TagInfo.json"
@@ -92,12 +93,20 @@
                                     {
                                         "tag": "games",
                                         "shortUrlsCount": 10,
-                                        "visitsCount": 521
+                                        "visitsSummary": {
+                                            "total": 521,
+                                            "nonBots": 521,
+                                            "bots": 0
+                                        }
                                     },
                                     {
                                         "tag": "shlink",
                                         "shortUrlsCount": 7,
-                                        "visitsCount": 1087
+                                        "visitsSummary": {
+                                            "total": 1087,
+                                            "nonBots": 1000,
+                                            "bots": 87
+                                        }
                                     }
                                 ],
                                 "pagination": {