From 8da8a1ad6b917e3e6367669bb2970c8fe5a95983 Mon Sep 17 00:00:00 2001
From: Ralph Slooten <axllent@gmail.com>
Date: Sun, 14 Apr 2024 12:36:45 +1200
Subject: [PATCH] Chore: Update API documentation regarding date/time searches
 & timezones

---
 server/apiv1/api.go           | 11 ++++++++---
 server/ui/api/v1/swagger.json | 12 +++++++++---
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/server/apiv1/api.go b/server/apiv1/api.go
index 700721503..977290cfe 100644
--- a/server/apiv1/api.go
+++ b/server/apiv1/api.go
@@ -84,7 +84,7 @@ func Search(w http.ResponseWriter, r *http.Request) {
 	//
 	// # Search messages
 	//
-	// Returns the latest messages matching a search.
+	// Returns messages matching [a search](https://mailpit.axllent.org/docs/usage/search-filters/), sorted by received date (descending).
 	//
 	//	Produces:
 	//	- application/json
@@ -111,7 +111,7 @@ func Search(w http.ResponseWriter, r *http.Request) {
 	//	    default: 50
 	//	  + name: tz
 	//	    in: query
-	//	    description: Timezone for `before:` & `after:` queries, eg: "Pacific/Auckland"
+	//	    description: [Timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used specifically for `before:` & `after:` searches (eg: "Pacific/Auckland").
 	//	    required: false
 	//	    type: string
 	//
@@ -155,7 +155,7 @@ func DeleteSearch(w http.ResponseWriter, r *http.Request) {
 	//
 	// # Delete messages by search
 	//
-	// Delete all messages matching a search.
+	// Delete all messages matching [a search](https://mailpit.axllent.org/docs/usage/search-filters/).
 	//
 	//	Produces:
 	//	- application/json
@@ -168,6 +168,11 @@ func DeleteSearch(w http.ResponseWriter, r *http.Request) {
 	//	    description: Search query
 	//	    required: true
 	//	    type: string
+	//	  + name: tz
+	//	    in: query
+	//	    description: [Timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used specifically for `before:` & `after:` searches (eg: "Pacific/Auckland").
+	//	    required: false
+	//	    type: string
 	//
 	//	Responses:
 	//		200: OKResponse
diff --git a/server/ui/api/v1/swagger.json b/server/ui/api/v1/swagger.json
index b092b3c70..984850e25 100644
--- a/server/ui/api/v1/swagger.json
+++ b/server/ui/api/v1/swagger.json
@@ -516,7 +516,7 @@
     },
     "/api/v1/search": {
       "get": {
-        "description": "Returns the latest messages matching a search.",
+        "description": "Returns messages matching [a search](https://mailpit.axllent.org/docs/usage/search-filters/), sorted by received date (descending).",
         "produces": [
           "application/json"
         ],
@@ -553,7 +553,7 @@
           },
           {
             "type": "string",
-            "description": "Timezone for `before:` \u0026 `after:` queries, eg: \"Pacific/Auckland\"",
+            "description": "[Timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used specifically for `before:` \u0026 `after:` searches (eg: \"Pacific/Auckland\").",
             "name": "tz",
             "in": "query"
           }
@@ -568,7 +568,7 @@
         }
       },
       "delete": {
-        "description": "Delete all messages matching a search.",
+        "description": "Delete all messages matching [a search](https://mailpit.axllent.org/docs/usage/search-filters/).",
         "produces": [
           "application/json"
         ],
@@ -588,6 +588,12 @@
             "name": "query",
             "in": "query",
             "required": true
+          },
+          {
+            "type": "string",
+            "description": "[Timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used specifically for `before:` \u0026 `after:` searches (eg: \"Pacific/Auckland\").",
+            "name": "tz",
+            "in": "query"
           }
         ],
         "responses": {