Skip to content

Commit

Permalink
fix: update OpenAPI specs for routes and correct docs for campaign en…
Browse files Browse the repository at this point in the history 
…dpoints (#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
  • Loading branch information
@dylancetin
dylancetin authored Nov 25, 2024
1 parent 882c49f commit fce46b2
Show file tree
Hide file tree
Showing 2 changed files with 169 additions and 80 deletions.
6 changes: 4 additions & 2 deletions docs/docs/content/apis/campaigns.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
243 changes: 165 additions & 78 deletions docs/swagger/collections.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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":
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1295,6 +1391,7 @@ paths:
description: start value of date range
schema:
type: string
format: date
- in: query
required: true
name: to
Expand All @@ -1304,6 +1401,7 @@ paths:
- in: query
name: id
description: campaign id/s to retrive view counts
required: true
schema:
type: string
responses:
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit fce46b2

Please sign in to comment.