knadh/listmonk
1
1
Fork 0
mirror of https://github.com/knadh/listmonk.git synced 2025-11-11 02:05:05 +08:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
* 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
This commit is contained in:
Dylan Cetin 2024-11-25 07:49:12 +03:00 • committed by GitHub
parent 882c49f1dd
commit fce46b2103
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 169 additions and 80 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/docs/content/apis/campaigns.md
View file

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

243
docs/swagger/collections.yaml
View file

@ -256,21 +256,56 @@ paths:
parameters: parameters:
- in: query - in: query
name: page name: page
description: number of records to skip description: Page number for paginated results.
required: false
schema: schema:
type: integer type: integer
format: int32 format: int32
- in: query - in: query
name: per_page 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: schema:
type: integer oneOf:
format: int32 - type: integer
description: Number of items to return per page
- type: string
enum: ["all"]
description: Return all results without pagination
- in: query - in: query
name: query name: query
description: query subscribers with an SQL expression. description: query subscribers with an SQL expression.
required: false
schema: schema:
type: string 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: responses:
"200": "200":
@ -719,36 +754,45 @@ paths:
operationId: getBounces operationId: getBounces
tags: tags:
- Bounces - 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: parameters:
- in: query - in: query
name: campaign_id name: campaign_id
description: bounce record retrieval of particular campaign description: Numeric identifier for retrieving bounce records associated with a specific campaign
schema: schema:
type: integer type: integer
- in: query - in: query
name: page name: page
description: total number of pages description: Page number for paginated results. Start from 1 for the first page
schema: schema:
type: integer type: integer
- in: query - in: query
name: per_page 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: 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: responses:
"200": "200":
description: list of bounce records description: list of bounce records
@ -856,32 +900,54 @@ paths:
- in: query - in: query
name: page name: page
description: total number of pages description: total number of pages
required: false
schema: schema:
type: integer type: integer
- in: query - in: query
name: per_page name: per_page
description: number of items per page description: number of items per page
required: false
schema: schema:
type: integer oneOf:
requestBody: - type: integer
required: true description: Number of items to return per page
description: output parameters form - type: string
content: enum: ["all"]
application/x-www-form-urlencoded: description: Return all results without pagination
schema: - in: query
type: object name: query
properties: description: Optional string to search a list by name.
query: required: false
description: Optional string to search a list by name. schema:
type: string type: string
order_by: - in: query
description: Field to sort results by. name|status|created_at|updated_at name: order_by
type: string description: Field to sort results by. name|status|created_at|updated_at
order: required: false
description: ASC|DESC Sort by ascending or descending order. schema:
type: string type: string
minimal: enum: ["name", "status", "created_at", "updated_at"]
type: boolean - 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: responses:
"200": "200":
description: list of metadata description: list of metadata
@ -1027,14 +1093,18 @@ paths:
requestBody: requestBody:
description: uploads and bulk imports of compressed CSV files description: uploads and bulk imports of compressed CSV files
content: content:
application/json: multipart/form-data:
schema: schema:
type: object type: object
properties: properties:
params: params:
type: string 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: file:
type: string type: string
format: binary
description: File for upload.
responses: responses:
"200": "200":
description: updated import status description: updated import status
@ -1086,45 +1156,64 @@ paths:
parameters: parameters:
- in: query - in: query
name: status 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: schema:
type: array type: array
items: items:
type: string type: string
enum: [scheduled, running, paused, cancelled] enum: ["scheduled", "running", "paused", "cancelled"]
- in: query - in: query
name: no_body name: no_body
description: boolean flag for response with/without body description: When set to true, returns response without body content
required: false
schema: schema:
type: boolean type: boolean
- in: query - in: query
name: page name: page
description: total number of pages description: Page number for paginated results.
required: false
schema: schema:
type: integer type: integer
- in: query - in: query
name: per_page 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: schema:
type: integer oneOf:
requestBody: - type: integer
required: true description: Number of items to return per page
description: output parameters form - type: string
content: enum: ["all"]
application/x-www-form-urlencoded: description: Return all results without pagination
schema: - in: query
type: object name: tags
properties: description: Filter campaigns by tags. Multiple tags can be specified by repeating the parameter
query: required: false
description: Optional string to search a list by name. schema:
type: string type: array
order_by: items:
description: Field to sort results by. name|status|created_at|updated_at type: string
type: string - in: query
order: name: order
description: ASC|DESC Sort by ascending or descending order. description: Determines the sort order of results. ASC for ascending, DESC for descending order
type: string 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: tags:
- Campaigns - Campaigns
responses: responses:
@ -1262,6 +1351,13 @@ paths:
operationId: getRunningCampaignStats operationId: getRunningCampaignStats
tags: tags:
- Campaigns - Campaigns
parameters:
- in: query
name: campaign_id
description: Campaign IDs to get stats for.
required: true
schema:
type: number
responses: responses:
"200": "200":
description: list of stats for given set of campaign ids description: list of stats for given set of campaign ids
@ -1295,6 +1391,7 @@ paths:
description: start value of date range description: start value of date range
schema: schema:
type: string type: string
format: date
- in: query - in: query
required: true required: true
name: to name: to
@ -1304,6 +1401,7 @@ paths:
- in: query - in: query
name: id name: id
description: campaign id/s to retrive view counts description: campaign id/s to retrive view counts
required: true
schema: schema:
type: string type: string
responses: responses:
@ -1332,17 +1430,6 @@ paths:
description: The id value of the campaign you want to get the preview of description: The id value of the campaign you want to get the preview of
schema: schema:
type: integer 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: responses:
"200": "200":
description: HTML Preview of requested campaign description: HTML Preview of requested campaign