Chore: Update API documentation regarding date/time searches & timezones

axllent · Apr 14, 2024 · 8da8a1a · 8da8a1a
1 parent 9e527ad
commit 8da8a1a
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 6 deletions.
diff --git 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
@@ -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": {