Nemcio/NodeBB
1
0
Fork 0
mirror of https://github.com/NodeBB/NodeBB.git synced 2025-10-26 08:36:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

spec: schema docs for new ACP dashboard subpage routes

Browse Source
This commit is contained in:
Julian Lam
2021-02-24 12:28:08 -05:00
parent 2f89b0d791
commit 0804d54759
12 changed files with 235 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
public/openapi/components/schemas/TopicObject.yaml
View File

@@ -168,8 +168,6 @@ TopicObject:
items:
type: string
description: HTML injected into the theme
index:
type: number
- type: object
description: Optional properties that may or may not be present (except for `tid`, which is always present, and is only here as a hack to pass validation)
properties:
@@ -184,6 +182,8 @@ TopicObject:
pinExpiryISO:
type: string
description: "`pinExpiry` rendered as an ISO 8601 format"
index:
type: number
required:
- tid
TopicObjectSlim:

1
public/openapi/components/schemas/UserObject.yaml
View File

@@ -127,6 +127,7 @@ UserObject:
groupTitle:
type: string
example: '["administrators","Staff"]'
nullable: true
groupTitleArray:
type: array
example:

47
public/openapi/components/schemas/admin/dashboard.yaml Normal file
View File

@@ -0,0 +1,47 @@
Stats:
type: object
properties:
stats:
type: array
items:
allOf:
- type: object
properties:
yesterday:
type: number
today:
type: number
lastweek:
type: number
thisweek:
type: number
lastmonth:
type: number
thismonth:
type: number
alltime:
type: number
dayIncrease:
type: string
dayTextClass:
type: string
weekIncrease:
type: string
weekTextClass:
type: string
monthIncrease:
type: string
monthTextClass:
type: string
name:
type: string
- type: object
description: Optional properties that may or may not be present (except for `cid`, which is always present, and is only here as a hack to pass validation)
properties:
name:
type: string
href:
type: string
description: Relative path to dashboard analytics sub-page, if applicable.
required:
- name

6
public/openapi/read.yaml
View File

@@ -63,6 +63,12 @@ paths:
$ref: 'read/admin.yaml'
/api/admin/dashboard:
$ref: 'read/admin/dashboard.yaml'
/api/admin/dashboard/logins:
$ref: 'read/admin/dashboard/logins.yaml'
/api/admin/dashboard/users:
$ref: 'read/admin/dashboard/users.yaml'
/api/admin/dashboard/topics:
$ref: 'read/admin/dashboard/topics.yaml'
"/api/admin/settings/{term}":
$ref: 'read/admin/settings/term.yaml'
/api/admin/settings/languages:

34
public/openapi/read/admin/dashboard.yaml
View File

@@ -40,39 +40,6 @@ get:
type: string
required:
- done
stats:
type: array
items:
type: object
properties:
yesterday:
type: number
today:
type: number
lastweek:
type: number
thisweek:
type: number
lastmonth:
type: number
thismonth:
type: number
alltime:
type: number
dayIncrease:
type: string
dayTextClass:
type: string
weekIncrease:
type: string
weekTextClass:
type: string
monthIncrease:
type: string
monthTextClass:
type: string
name:
type: string
canRestart:
type: boolean
lastrestart:
@@ -93,4 +60,5 @@ get:
description: An ISO 8601 formatted date string (complementing `timestamp`)
showSystemControls:
type: boolean
- $ref: ../../components/schemas/admin/dashboard.yaml#/Stats
- $ref: ../../components/schemas/CommonProps.yaml#/CommonProps

55
public/openapi/read/admin/dashboard/logins.yaml Normal file
View File

@@ -0,0 +1,55 @@
get:
tags:
- admin
summary: Get detailed login analytics
responses:
"200":
description: A JSON object containing more detailed analytics related to user login sessions.
content:
application/json:
schema:
allOf:
- type: object
properties:
set:
type: string
description: The analytics set that is being queried
query:
additionalProperties:
description: An object containing the query string parameters, if any
summary:
type: object
properties:
day:
type: number
week:
type: number
month:
type: number
sessions:
type: array
items:
type: object
properties:
ip:
type: string
uuid:
type: string
datetime:
type: number
platform:
type: string
browser:
type: string
version:
type: string
current:
type: boolean
datetimeISO:
type: string
user:
$ref: ../../../components/schemas/UserObj.yaml#/UserObj
loginDays:
type: number
- $ref: ../../../components/schemas/admin/dashboard.yaml#/Stats
- $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps

34
public/openapi/read/admin/dashboard/topics.yaml Normal file
View File

@@ -0,0 +1,34 @@
get:
tags:
- admin
summary: Get detailed user registration analytics
responses:
"200":
description: A JSON object containing more detailed analytics related to user registrations.
content:
application/json:
schema:
allOf:
- type: object
properties:
set:
type: string
description: The analytics set that is being queried
query:
additionalProperties:
description: An object containing the query string parameters, if any
summary:
type: object
properties:
day:
type: number
week:
type: number
month:
type: number
topics:
type: array
items:
$ref: ../../../components/schemas/TopicObject.yaml#/TopicObject
- $ref: ../../../components/schemas/admin/dashboard.yaml#/Stats
- $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps

34
public/openapi/read/admin/dashboard/users.yaml Normal file
View File

@@ -0,0 +1,34 @@
get:
tags:
- admin
summary: Get detailed user registration analytics
responses:
"200":
description: A JSON object containing more detailed analytics related to user registrations.
content:
application/json:
schema:
allOf:
- type: object
properties:
set:
type: string
description: The analytics set that is being queried
query:
additionalProperties:
description: An object containing the query string parameters, if any
summary:
type: object
properties:
day:
type: number
week:
type: number
month:
type: number
users:
type: array
items:
$ref: ../../../components/schemas/UserObject.yaml#/UserObject
- $ref: ../../../components/schemas/admin/dashboard.yaml#/Stats
- $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps

2
public/openapi/write.yaml
View File

@@ -122,5 +122,7 @@ paths:
$ref: 'write/posts/pid/diffs/timestamp.yaml'
/admin/settings/{setting}:
$ref: 'write/admin/settings/setting.yaml'
/admin/analytics/{set}:
$ref: 'write/admin/analytics/set.yaml'
/files/:
$ref: 'write/files.yaml'

46
public/openapi/write/admin/analytics/set.yaml Normal file
View File

@@ -0,0 +1,46 @@
get:
tags:
- admin
summary: get analytics data
description: This operation retrieves analytics data from NodeBB. It is only accessible to administrators.
parameters:
- in: path
name: set
schema:
type: string
required: true
description: analytics set to retrieve
example: topics
- in: query
name: units
schema:
type: string
enum: [hours, days]
description: Whether to display dashboard data segmented daily or hourly
example: days
- in: query
name: until
schema:
type: number
description: A UNIX timestamp denoting the end of the analytics reporting period
example: ''
- in: query
name: count
schema:
type: number
description: The number of entries to return (e.g. if `units` is `hourly`, and `count` is `24`, the result set will contain 24 hours' worth of analytics)
example: 20
responses:
'200':
description: Analytics set retrieved
content:
application/json:
schema:
type: object
properties:
status:
$ref: ../../../components/schemas/Status.yaml#/Status
response:
type: array
items:
type: number

4
src/controllers/admin/dashboard.js
View File

@@ -174,7 +174,7 @@ async function getStatsFromAnalytics(set, field) {
const sum = arr => arr.reduce((memo, cur) => memo + cur, 0);
const results = {
yesterday: sum(data.slice(-2)),
today: data.slice(-1),
today: data.slice(-1)[0],
lastweek: sum(data.slice(-14)),
thisweek: sum(data.slice(-7)),
lastmonth: sum(data.slice(0)), // entire set
@@ -282,7 +282,7 @@ dashboardController.getUsers = async (req, res) => {
const end = parseInt(req.query.until, 10) || Date.now();
const start = end - (1000 * 60 * 60 * (req.query.units === 'days' ? 24 : 1) * (req.query.count || (req.query.units === 'days' ? 30 : 24)));
const uids = await db.getSortedSetRangeByScore('users:joindate', 0, 500, start, end);
const users = await user.getUsersFields(uids, ['uid', 'username', 'email', 'joindate']);
const users = await user.getUsersData(uids);
res.render('admin/dashboard/users', {
set: 'registrations',

6
test/api.js
View File

@@ -486,7 +486,11 @@ describe('API', async () => {
if (obj.allOf) {
obj = { properties: flattenAllOf(obj.allOf) };
} else {
required = required.concat(obj.required ? obj.required : Object.keys(obj.properties));
try {
required = required.concat(obj.required ? obj.required : Object.keys(obj.properties));
} catch (e) {
assert.fail(`Syntax error re: allOf, perhaps you allOf'd an array? (path: ${method} ${path}, context: ${context})`);
}
}
return { ...memo, ...obj.properties };