fix: update OpenAPI specs for routes and correct docs for campaign endpoints (#2179)

* Fix API Docs for campaign routes' params

1. Added no_body for some. These existed in OpenApi spec but was not present in the docs
2. GET /api/campaigns/analytics/{type} fixed params description for "from" and "to"

* OpenApi Specs GET routes and File Type Fix

This commit fixes some routes' openapi specs by following lismonk.app/docs/

1. GET Routes can't have a body. All params spesified in the body is moved up to query params
2. On the route /import/subscribers POST fixed content type to Multipart, added example params and fixed file type to string/binary
3. And added required: false to many

docs/docs/content/apis/campaigns.md

@@ -37,6 +37,7 @@ Retrieve all campaigns.
 | tags     | []string |          | Tags to filter campaigns. Repeat in the query for multiple values.   |
 | page     | number   |          | Page number for paginated results.                                   |
 | per_page | number   |          | Results per page. Set as 'all' for all results.                      |
+| no_body  | boolean   |          | When set to true, returns response without body content.                      |
 
 ##### Example Response
 
@@ -94,6 +95,7 @@ Retrieve a specific campaign.
 | Name        | Type      | Required | Description  |
 |:------------|:----------|:---------|:-------------|
 | campaign_id | number    | Yes      | Campaign ID. |
+| no_body  | boolean   |          | When set to true, returns response without body content.                      |
 
 ##### Example Request
 
@@ -201,8 +203,8 @@ Retrieve stats of specified campaigns.
 |:------------|:----------|:---------|:----------------------------------------------|
 | id          |number\[\] | Yes      | Campaign IDs to get stats for.                |
 | type        |string     | Yes      | Analytics type: views, links, clicks, bounces |
-| from        |string     | Yes      | Campaign IDs to get stats for.                |
-| to          |string     | Yes      | Campaign IDs to get stats for.                |
+| from        |string     | Yes      | Start value of date range.                |
+| to          |string     | Yes      | End value of date range.                |
 
 
 ##### Example Request

docs/swagger/collections.yaml

@@ -256,21 +256,56 @@ paths:
       parameters:
         - in: query
           name: page
-          description: number of records to skip
+          description: Page number for paginated results.
+          required: false
           schema:
             type: integer
             format: int32
         - in: query
           name: per_page
-          description: max number of records to return per page
+          description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
+          required: false
           schema:
-            type: integer
-            format: int32
+            oneOf:
+              - type: integer
+                description: Number of items to return per page
+              - type: string
+                enum: ["all"]
+                description: Return all results without pagination
         - in: query
           name: query
           description: query subscribers with an SQL expression.
+          required: false
           schema:
             type: string
+        - in: query
+          name: order_by
+          description: Result sorting field. Options are name, status, created_at, updated_at
+          required: false
+          schema:
+            type: string
+            enum: ["name", "status", "created_at", "updated_at"]
+        - in: query
+          name: order
+          description: ASC|DESC Sort by ascending or descending order.
+          required: false
+          schema:
+            type: string
+            enum: ["ASC", "DESC"]
+        - in: query
+          name: subscription_status
+          description: Subscription status to filter by if there are one or more list_ids.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: list_id
+          description: ID of lists to filter by. Repeat in the query for multiple values.
+          required: false
+          schema:
+            type: array
+            items:
+              type: integer
 
       responses:
         "200":
@@ -719,36 +754,45 @@ paths:
       operationId: getBounces
       tags:
         - Bounces
-      requestBody:
-        description: output parameters form
-        required: true
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                source:
-                  type: string
-                order_by:
-                  type: string
-                order:
-                  type: string
       parameters:
         - in: query
           name: campaign_id
-          description: bounce record retrieval of particular campaign
+          description: Numeric identifier for retrieving bounce records associated with a specific campaign
           schema:
             type: integer
         - in: query
           name: page
-          description: total number of pages
+          description: Page number for paginated results. Start from 1 for the first page
           schema:
             type: integer
         - in: query
           name: per_page
-          description: number of items per page
+          description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
           schema:
-            type: integer
+            oneOf:
+              - type: integer
+                description: Number of items to return per page
+              - type: string
+                enum:
+                  - "all"
+                description: Return all results without pagination
+        - in: query
+          name: source
+          description: Filter bounce records by their source of origin
+          schema:
+            type: string
+        - in: query
+          name: order_by
+          description: Specifies the field by which to sort the bounce records. Available options are 'email', 'campaign_name', 'source', and 'created_at'
+          schema:
+            type: string
+            enum: ["email", "campaign_name", "source", "created_at"]
+        - in: query
+          name: order
+          description: Determines the sort order of results. Use 'asc' for ascending or 'desc' for descending order
+          schema:
+            type: string
+            enum: ["asc", "desc"]
       responses:
         "200":
           description: list of bounce records
@@ -856,32 +900,54 @@ paths:
         - in: query
           name: page
           description: total number of pages
+          required: false
           schema:
             type: integer
         - in: query
           name: per_page
           description: number of items per page
+          required: false
           schema:
-            type: integer
-      requestBody:
-        required: true
-        description: output parameters form
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                query:
-                  description: Optional string to search a list by name.
-                  type: string
-                order_by:
-                  description: Field to sort results by. name|status|created_at|updated_at
-                  type: string
-                order:
-                  description: ASC|DESC Sort by ascending or descending order.
-                  type: string
-                minimal:
-                  type: boolean
+            oneOf:
+              - type: integer
+                description: Number of items to return per page
+              - type: string
+                enum: ["all"]
+                description: Return all results without pagination
+        - in: query
+          name: query
+          description: Optional string to search a list by name.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: order_by
+          description: Field to sort results by. name|status|created_at|updated_at
+          required: false
+          schema:
+            type: string
+            enum: ["name", "status", "created_at", "updated_at"]
+        - in: query
+          name: order
+          description: ASC|DESC Sort by ascending or descending order.
+          required: false
+          schema:
+            type: string
+            enum: ["ASC", "DESC"]
+        - in: query
+          name: minimal
+          description: When set to true, returns response without body content
+          required: false
+          schema:
+            type: boolean
+        - in: query
+          name: tag
+          description: Tags to filter lists. Repeat in the query for multiple values.
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
       responses:
         "200":
           description: list of metadata
@@ -1027,14 +1093,18 @@ paths:
       requestBody:
         description: uploads and bulk imports of compressed CSV files
         content:
-          application/json:
+          multipart/form-data:
             schema:
               type: object
               properties:
                 params:
                   type: string
+                  description: JSON string containing import parameters for more detail https://listmonk.app/docs/apis/import/#params-json-string
+                  example: '{"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}'
                 file:
                   type: string
+                  format: binary
+                  description: File for upload.
       responses:
         "200":
           description: updated import status
@@ -1086,45 +1156,64 @@ paths:
       parameters:
         - in: query
           name: status
-          description: status flag of campaign
+          description: Filter campaigns by status. Multiple status values can be specified by repeating the parameter
+          required: false
           schema:
             type: array
             items:
               type: string
-              enum: [scheduled, running, paused, cancelled]
+              enum: ["scheduled", "running", "paused", "cancelled"]
         - in: query
           name: no_body
-          description: boolean flag for response with/without body
+          description: When set to true, returns response without body content
+          required: false
           schema:
             type: boolean
         - in: query
           name: page
-          description: total number of pages
+          description: Page number for paginated results.
+          required: false
           schema:
             type: integer
         - in: query
           name: per_page
-          description: number of items per page
+          description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
+          required: false
           schema:
-            type: integer
-      requestBody:
-        required: true
-        description: output parameters form
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                query:
-                  description: Optional string to search a list by name.
-                  type: string
-                order_by:
-                  description: Field to sort results by. name|status|created_at|updated_at
-                  type: string
-                order:
-                  description: ASC|DESC Sort by ascending or descending order.
-                  type: string
-
+            oneOf:
+              - type: integer
+                description: Number of items to return per page
+              - type: string
+                enum: ["all"]
+                description: Return all results without pagination
+        - in: query
+          name: tags
+          description: Filter campaigns by tags. Multiple tags can be specified by repeating the parameter
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+        - in: query
+          name: order
+          description: Determines the sort order of results. ASC for ascending, DESC for descending order
+          required: false
+          schema:
+            type: string
+            enum: ["ASC", "DESC"]
+        - in: query
+          name: order_by
+          description: Specifies the field by which to sort the campaigns. Available options are 'name', 'status', 'created_at', and 'updated_at'
+          required: false
+          schema:
+            type: string
+            enum: ["name", "status", "created_at", "updated_at"]
+        - in: query
+          name: query
+          description: SQL query expression to filter campaigns by custom criteria
+          required: false
+          schema:
+            type: string
       tags:
         - Campaigns
       responses:
@@ -1262,6 +1351,13 @@ paths:
       operationId: getRunningCampaignStats
       tags:
         - Campaigns
+      parameters:
+        - in: query
+          name: campaign_id
+          description: Campaign IDs to get stats for.
+          required: true
+          schema:
+            type: number
       responses:
         "200":
           description: list of stats for given set of campaign ids
@@ -1295,6 +1391,7 @@ paths:
           description: start value of date range
           schema:
             type: string
+            format: date
         - in: query
           required: true
           name: to
@@ -1304,6 +1401,7 @@ paths:
         - in: query
           name: id
           description: campaign id/s to retrive view counts
+          required: true
           schema:
             type: string
       responses:
@@ -1332,17 +1430,6 @@ paths:
           description: The id value of the campaign you want to get the preview of
           schema:
             type: integer
-      requestBody:
-        required: true
-        description: template id
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                template_id:
-                  description: template id
-                  type: integer
       responses:
         "200":
           description: HTML Preview of requested campaign