Skip to content

Commit fce46b2

Browse files
dylancetindylancetin
authored
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
1 parent 882c49f commit fce46b2

File tree

2 files changed

+169
-80
lines changed

2 files changed

+169
-80
lines changed

‎docs/docs/content/apis/campaigns.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Retrieve all campaigns.
3737
| tags | []string | | Tags to filter campaigns. Repeat in the query for multiple values. |
3838
| page | number | | Page number for paginated results. |
3939
| per_page | number | | Results per page. Set as 'all' for all results. |
40+
| no_body | boolean | | When set to true, returns response without body content. |
4041

4142
##### Example Response
4243

@@ -94,6 +95,7 @@ Retrieve a specific campaign.
9495
| Name | Type | Required | Description |
9596
|:------------|:----------|:---------|:-------------|
9697
| campaign_id | number | Yes | Campaign ID. |
98+
| no_body | boolean | | When set to true, returns response without body content. |
9799

98100
##### Example Request
99101

@@ -201,8 +203,8 @@ Retrieve stats of specified campaigns.
201203
|:------------|:----------|:---------|:----------------------------------------------|
202204
| id |number\[\] | Yes | Campaign IDs to get stats for. |
203205
| type |string | Yes | Analytics type: views, links, clicks, bounces |
204-
| from |string | Yes | Campaign IDs to get stats for. |
205-
| to |string | Yes | Campaign IDs to get stats for. |
206+
| from |string | Yes | Start value of date range. |
207+
| to |string | Yes | End value of date range. |
206208

207209

208210
##### Example Request

‎docs/swagger/collections.yaml‎

Lines changed: 165 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -256,21 +256,56 @@ paths:
256256
parameters:
257257
- in: query
258258
name: page
259-
description: number of records to skip
259+
description: Page number for paginated results.
260+
required: false
260261
schema:
261262
type: integer
262263
format: int32
263264
- in: query
264265
name: per_page
265-
description: max number of records to return per page
266+
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
267+
required: false
266268
schema:
267-
type: integer
268-
format: int32
269+
oneOf:
270+
- type: integer
271+
description: Number of items to return per page
272+
- type: string
273+
enum: ["all"]
274+
description: Return all results without pagination
269275
- in: query
270276
name: query
271277
description: query subscribers with an SQL expression.
278+
required: false
279+
schema:
280+
type: string
281+
- in: query
282+
name: order_by
283+
description: Result sorting field. Options are name, status, created_at, updated_at
284+
required: false
272285
schema:
273286
type: string
287+
enum: ["name", "status", "created_at", "updated_at"]
288+
- in: query
289+
name: order
290+
description: ASC|DESC Sort by ascending or descending order.
291+
required: false
292+
schema:
293+
type: string
294+
enum: ["ASC", "DESC"]
295+
- in: query
296+
name: subscription_status
297+
description: Subscription status to filter by if there are one or more list_ids.
298+
required: false
299+
schema:
300+
type: string
301+
- in: query
302+
name: list_id
303+
description: ID of lists to filter by. Repeat in the query for multiple values.
304+
required: false
305+
schema:
306+
type: array
307+
items:
308+
type: integer
274309

275310
responses:
276311
"200":
@@ -719,36 +754,45 @@ paths:
719754
operationId: getBounces
720755
tags:
721756
- Bounces
722-
requestBody:
723-
description: output parameters form
724-
required: true
725-
content:
726-
application/x-www-form-urlencoded:
727-
schema:
728-
type: object
729-
properties:
730-
source:
731-
type: string
732-
order_by:
733-
type: string
734-
order:
735-
type: string
736757
parameters:
737758
- in: query
738759
name: campaign_id
739-
description: bounce record retrieval of particular campaign
760+
description: Numeric identifier for retrieving bounce records associated with a specific campaign
740761
schema:
741762
type: integer
742763
- in: query
743764
name: page
744-
description: total number of pages
765+
description: Page number for paginated results. Start from 1 for the first page
745766
schema:
746767
type: integer
747768
- in: query
748769
name: per_page
749-
description: number of items per page
770+
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
750771
schema:
751-
type: integer
772+
oneOf:
773+
- type: integer
774+
description: Number of items to return per page
775+
- type: string
776+
enum:
777+
- "all"
778+
description: Return all results without pagination
779+
- in: query
780+
name: source
781+
description: Filter bounce records by their source of origin
782+
schema:
783+
type: string
784+
- in: query
785+
name: order_by
786+
description: Specifies the field by which to sort the bounce records. Available options are 'email', 'campaign_name', 'source', and 'created_at'
787+
schema:
788+
type: string
789+
enum: ["email", "campaign_name", "source", "created_at"]
790+
- in: query
791+
name: order
792+
description: Determines the sort order of results. Use 'asc' for ascending or 'desc' for descending order
793+
schema:
794+
type: string
795+
enum: ["asc", "desc"]
752796
responses:
753797
"200":
754798
description: list of bounce records
@@ -856,32 +900,54 @@ paths:
856900
- in: query
857901
name: page
858902
description: total number of pages
903+
required: false
859904
schema:
860905
type: integer
861906
- in: query
862907
name: per_page
863908
description: number of items per page
909+
required: false
864910
schema:
865-
type: integer
866-
requestBody:
867-
required: true
868-
description: output parameters form
869-
content:
870-
application/x-www-form-urlencoded:
871-
schema:
872-
type: object
873-
properties:
874-
query:
875-
description: Optional string to search a list by name.
876-
type: string
877-
order_by:
878-
description: Field to sort results by. name|status|created_at|updated_at
879-
type: string
880-
order:
881-
description: ASC|DESC Sort by ascending or descending order.
882-
type: string
883-
minimal:
884-
type: boolean
911+
oneOf:
912+
- type: integer
913+
description: Number of items to return per page
914+
- type: string
915+
enum: ["all"]
916+
description: Return all results without pagination
917+
- in: query
918+
name: query
919+
description: Optional string to search a list by name.
920+
required: false
921+
schema:
922+
type: string
923+
- in: query
924+
name: order_by
925+
description: Field to sort results by. name|status|created_at|updated_at
926+
required: false
927+
schema:
928+
type: string
929+
enum: ["name", "status", "created_at", "updated_at"]
930+
- in: query
931+
name: order
932+
description: ASC|DESC Sort by ascending or descending order.
933+
required: false
934+
schema:
935+
type: string
936+
enum: ["ASC", "DESC"]
937+
- in: query
938+
name: minimal
939+
description: When set to true, returns response without body content
940+
required: false
941+
schema:
942+
type: boolean
943+
- in: query
944+
name: tag
945+
description: Tags to filter lists. Repeat in the query for multiple values.
946+
required: false
947+
schema:
948+
type: array
949+
items:
950+
type: string
885951
responses:
886952
"200":
887953
description: list of metadata
@@ -1027,14 +1093,18 @@ paths:
10271093
requestBody:
10281094
description: uploads and bulk imports of compressed CSV files
10291095
content:
1030-
application/json:
1096+
multipart/form-data:
10311097
schema:
10321098
type: object
10331099
properties:
10341100
params:
10351101
type: string
1102+
description: JSON string containing import parameters for more detail https://listmonk.app/docs/apis/import/#params-json-string
1103+
example: '{"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}'
10361104
file:
10371105
type: string
1106+
format: binary
1107+
description: File for upload.
10381108
responses:
10391109
"200":
10401110
description: updated import status
@@ -1086,45 +1156,64 @@ paths:
10861156
parameters:
10871157
- in: query
10881158
name: status
1089-
description: status flag of campaign
1159+
description: Filter campaigns by status. Multiple status values can be specified by repeating the parameter
1160+
required: false
10901161
schema:
10911162
type: array
10921163
items:
10931164
type: string
1094-
enum: [scheduled, running, paused, cancelled]
1165+
enum: ["scheduled", "running", "paused", "cancelled"]
10951166
- in: query
10961167
name: no_body
1097-
description: boolean flag for response with/without body
1168+
description: When set to true, returns response without body content
1169+
required: false
10981170
schema:
10991171
type: boolean
11001172
- in: query
11011173
name: page
1102-
description: total number of pages
1174+
description: Page number for paginated results.
1175+
required: false
11031176
schema:
11041177
type: integer
11051178
- in: query
11061179
name: per_page
1107-
description: number of items per page
1180+
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
1181+
required: false
11081182
schema:
1109-
type: integer
1110-
requestBody:
1111-
required: true
1112-
description: output parameters form
1113-
content:
1114-
application/x-www-form-urlencoded:
1115-
schema:
1116-
type: object
1117-
properties:
1118-
query:
1119-
description: Optional string to search a list by name.
1120-
type: string
1121-
order_by:
1122-
description: Field to sort results by. name|status|created_at|updated_at
1123-
type: string
1124-
order:
1125-
description: ASC|DESC Sort by ascending or descending order.
1126-
type: string
1127-
1183+
oneOf:
1184+
- type: integer
1185+
description: Number of items to return per page
1186+
- type: string
1187+
enum: ["all"]
1188+
description: Return all results without pagination
1189+
- in: query
1190+
name: tags
1191+
description: Filter campaigns by tags. Multiple tags can be specified by repeating the parameter
1192+
required: false
1193+
schema:
1194+
type: array
1195+
items:
1196+
type: string
1197+
- in: query
1198+
name: order
1199+
description: Determines the sort order of results. ASC for ascending, DESC for descending order
1200+
required: false
1201+
schema:
1202+
type: string
1203+
enum: ["ASC", "DESC"]
1204+
- in: query
1205+
name: order_by
1206+
description: Specifies the field by which to sort the campaigns. Available options are 'name', 'status', 'created_at', and 'updated_at'
1207+
required: false
1208+
schema:
1209+
type: string
1210+
enum: ["name", "status", "created_at", "updated_at"]
1211+
- in: query
1212+
name: query
1213+
description: SQL query expression to filter campaigns by custom criteria
1214+
required: false
1215+
schema:
1216+
type: string
11281217
tags:
11291218
- Campaigns
11301219
responses:
@@ -1262,6 +1351,13 @@ paths:
12621351
operationId: getRunningCampaignStats
12631352
tags:
12641353
- Campaigns
1354+
parameters:
1355+
- in: query
1356+
name: campaign_id
1357+
description: Campaign IDs to get stats for.
1358+
required: true
1359+
schema:
1360+
type: number
12651361
responses:
12661362
"200":
12671363
description: list of stats for given set of campaign ids
@@ -1295,6 +1391,7 @@ paths:
12951391
description: start value of date range
12961392
schema:
12971393
type: string
1394+
format: date
12981395
- in: query
12991396
required: true
13001397
name: to
@@ -1304,6 +1401,7 @@ paths:
13041401
- in: query
13051402
name: id
13061403
description: campaign id/s to retrive view counts
1404+
required: true
13071405
schema:
13081406
type: string
13091407
responses:
@@ -1332,17 +1430,6 @@ paths:
13321430
description: The id value of the campaign you want to get the preview of
13331431
schema:
13341432
type: integer
1335-
requestBody:
1336-
required: true
1337-
description: template id
1338-
content:
1339-
application/x-www-form-urlencoded:
1340-
schema:
1341-
type: object
1342-
properties:
1343-
template_id:
1344-
description: template id
1345-
type: integer
13461433
responses:
13471434
"200":
13481435
description: HTML Preview of requested campaign

0 commit comments

Comments
 (0)