diff --git a/public/openapi/api/admin/advanced/cache.yaml b/public/openapi/api/admin/advanced/cache.yaml new file mode 100644 index 000000000000..4d54740eb94a --- /dev/null +++ b/public/openapi/api/admin/advanced/cache.yaml @@ -0,0 +1,91 @@ +get: + tags: + - admin + summary: Get system cache info + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + postCache: + type: object + properties: + length: + type: number + max: + type: number + nullable: true + itemCount: + type: number + percentFull: + type: number + avgPostSize: + type: number + hits: + type: string + misses: + type: string + hitRatio: + type: string + groupCache: + type: object + properties: + length: + type: number + max: + type: number + itemCount: + type: number + percentFull: + type: number + hits: + type: string + misses: + type: string + hitRatio: + type: string + localCache: + type: object + properties: + length: + type: number + max: + type: number + itemCount: + type: number + percentFull: + type: number + dump: + type: boolean + hits: + type: string + misses: + type: string + hitRatio: + type: string + objectCache: + type: object + properties: + length: + type: number + max: + type: number + itemCount: + type: number + percentFull: + type: number + hits: + type: string + misses: + type: string + hitRatio: + type: string + required: + - postCache + - groupCache + - localCache + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/database.yaml b/public/openapi/api/admin/advanced/database.yaml new file mode 100644 index 000000000000..ae2676b36934 --- /dev/null +++ b/public/openapi/api/admin/advanced/database.yaml @@ -0,0 +1,14 @@ +get: + tags: + - admin + summary: Get database information + responses: + "200": + description: "A JSON object with database status information" + content: + application/json: + schema: + properties: {} + additionalProperties: + type: object + description: Each database configured will have an entry here with information about its runtime status \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/errors.yaml b/public/openapi/api/admin/advanced/errors.yaml new file mode 100644 index 000000000000..a409e477233e --- /dev/null +++ b/public/openapi/api/admin/advanced/errors.yaml @@ -0,0 +1,38 @@ +get: + tags: + - admin + summary: Get server-side errors + responses: + "200": + description: "A JSON object containing server-side errors" + content: + application/json: + schema: + allOf: + - type: object + properties: + not-found: + type: array + items: + type: object + properties: + value: + type: string + description: Path to the requested URL that returned a 404 + score: + type: number + description: The number of times that URL was requested + analytics: + type: object + properties: + not-found: + type: array + description: 404 responses groups by day, from 6 days ago, to present day + items: + type: number + toobusy: + type: array + description: 503 responses groups by day, from 6 days ago, to present day + items: + type: number + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/errors/export.yaml b/public/openapi/api/admin/advanced/errors/export.yaml new file mode 100644 index 000000000000..4cb6a3febdec --- /dev/null +++ b/public/openapi/api/admin/advanced/errors/export.yaml @@ -0,0 +1,12 @@ +get: + tags: + - admin + summary: Export errors (.csv) + responses: + "200": + description: "A CSV file containing server-side errors" + content: + text/csv: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/events.yaml b/public/openapi/api/admin/advanced/events.yaml new file mode 100644 index 000000000000..72ce4be7e2c1 --- /dev/null +++ b/public/openapi/api/admin/advanced/events.yaml @@ -0,0 +1,65 @@ +get: + tags: + - admin + summary: Get event log + parameters: + - in: query + name: type + schema: + type: string + description: Event name to filter by + example: config-change + - in: query + name: start + schema: + type: string + description: Start date to filter by + example: '' + - in: query + name: end + schema: + type: string + description: End date to filter by + example: '' + - in: query + name: perPage + schema: + type: string + description: Limit the number of events returned per page + example: 20 + responses: + "200": + description: "A JSON object containing " + content: + application/json: + schema: + allOf: + - type: object + properties: + events: + type: array + items: + type: object + properties: + type: + type: string + additionalProperties: + description: Each individual event as added by core/plugins can append their own metadata related to the event + - $ref: ../../../components/schemas/Pagination.yaml#/Pagination + - type: object + properties: + types: + type: array + items: + type: object + properties: + value: + type: string + name: + type: string + selected: + type: boolean + query: + additionalProperties: + description: An object containing the query string parameters, if any + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/hooks.yaml b/public/openapi/api/admin/advanced/hooks.yaml new file mode 100644 index 000000000000..d43da546036a --- /dev/null +++ b/public/openapi/api/admin/advanced/hooks.yaml @@ -0,0 +1,45 @@ +get: + tags: + - admin + summary: Get active plugin hooks + responses: + "200": + description: "A JSON object containing all hooks with active listeners" + content: + application/json: + schema: + allOf: + - type: object + properties: + hooks: + type: array + items: + type: object + properties: + hookName: + type: string + description: The name of the hook (also the name used in code) + methods: + type: array + items: + type: object + properties: + id: + type: string + description: Plugin listening to this hook + priority: + type: number + description: Priority level, lower priorities are executed earlier + method: + type: string + description: Stringified method for examination + index: + type: string + description: Internal counter used for DOM element ids + index: + type: string + description: Internal counter used for DOM element ids + count: + type: number + description: The number of listeners subscribed to this hook + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/advanced/logs.yaml b/public/openapi/api/admin/advanced/logs.yaml new file mode 100644 index 000000000000..57c1245a34a2 --- /dev/null +++ b/public/openapi/api/admin/advanced/logs.yaml @@ -0,0 +1,17 @@ +get: + tags: + - admin + summary: Get server-side log output + responses: + "200": + description: "A JSON object containing the server-side log" + content: + application/json: + schema: + allOf: + - type: object + properties: + data: + type: string + description: Output of the server-side log file + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/analytics.yaml b/public/openapi/api/admin/analytics.yaml new file mode 100644 index 000000000000..508325aaceb9 --- /dev/null +++ b/public/openapi/api/admin/analytics.yaml @@ -0,0 +1,58 @@ +get: + tags: + - admin + summary: Get site analytics + parameters: + - 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: "A JSON object containing analytics data" + content: + application/json: + schema: + type: object + properties: + query: + additionalProperties: + description: The query string passed in + result: + type: object + properties: + uniquevisitors: + type: array + items: + type: number + pageviews: + type: array + items: + type: number + pageviews:registered: + type: array + items: + type: number + pageviews:bot: + type: array + items: + type: number + pageviews:guest: + type: array + items: + type: number \ No newline at end of file diff --git a/public/openapi/api/admin/appearance.yaml b/public/openapi/api/admin/appearance.yaml new file mode 100644 index 000000000000..37313c66a681 --- /dev/null +++ b/public/openapi/api/admin/appearance.yaml @@ -0,0 +1,18 @@ +get: + tags: + - admin + summary: Get appearance settings + parameters: + - name: term + in: path + required: true + schema: + type: string + example: themes + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/category/uploadpicture.yaml b/public/openapi/api/admin/category/uploadpicture.yaml new file mode 100644 index 000000000000..76ca5c1a7187 --- /dev/null +++ b/public/openapi/api/admin/category/uploadpicture.yaml @@ -0,0 +1,37 @@ +post: + tags: + - admin + summary: Update category picture (via image upload) + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + cid: + type: number + description: Category identifier whose picture will be set after successful upload + example: 1 + files: + type: array + items: + type: string + format: binary + required: + - cid + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/dashboard.yaml b/public/openapi/api/admin/dashboard.yaml new file mode 100644 index 000000000000..296a8c6b6170 --- /dev/null +++ b/public/openapi/api/admin/dashboard.yaml @@ -0,0 +1,96 @@ +get: + tags: + - admin + summary: Get administrative dashboard + responses: + "200": + description: A JSON object containing dashboard data + content: + application/json: + schema: + allOf: + - type: object + properties: + version: + type: string + lookupFailed: + type: boolean + latestVersion: + type: string + nullable: true + upgradeAvailable: + type: boolean + nullable: true + currentPrerelease: + type: boolean + notices: + type: array + items: + type: object + properties: + done: + type: boolean + doneText: + type: string + notDoneText: + type: string + tooltip: + type: string + link: + 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: + nullable: true + type: object + properties: + uid: + type: number + description: A user identifier + ip: + type: string + timestamp: + type: number + user: + $ref: ../../components/schemas/UserObject.yaml#/UserObject + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + showSystemControls: + type: boolean + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/development/info.yaml b/public/openapi/api/admin/development/info.yaml new file mode 100644 index 000000000000..e576561e305d --- /dev/null +++ b/public/openapi/api/admin/development/info.yaml @@ -0,0 +1,160 @@ +get: + tags: + - admin + summary: Get process/system information + responses: + "200": + description: "A JSON object containing process and system information" + content: + application/json: + schema: + allOf: + - type: object + properties: + info: + type: array + items: + type: object + properties: + process: + type: object + properties: + port: + description: An array containing the port numbers configured to be used by NodeBB processes + oneOf: + - type: array + items: + oneOf: + - type: string + - type: number + - type: string + - type: number + pid: + type: number + description: Process id + title: + type: number + description: Executable + version: + type: number + description: NodeBB version + memoryUsage: + type: object + properties: + rss: + type: number + heapTotal: + type: number + heapUsed: + type: number + external: + type: number + arrayBuffers: + type: number + humanReadable: + type: number + required: + - rss + - heapTotal + - heapUsed + - external + - humanReadable + uptime: + type: number + cpuUsage: + type: object + properties: + user: + type: string + system: + type: string + os: + type: object + properties: + hostname: + type: string + type: + type: string + platform: + type: string + arch: + type: string + release: + type: string + load: + type: string + description: CPU load + nodebb: + type: object + properties: + isPrimary: + type: boolean + isCluster: + type: boolean + runJobs: + type: boolean + jobsDisabled: + type: boolean + git: + type: object + properties: + hash: + type: string + hashShort: + type: string + branch: + type: string + stats: + type: object + properties: + onlineGuestCount: + type: number + onlineRegisteredCount: + type: number + socketCount: + type: number + users: + type: object + properties: + categories: + type: number + recent: + type: number + unread: + type: number + topics: + type: number + category: + type: number + topics: + type: array + id: + type: string + infoJSON: + type: string + description: "`info`, but stringified" + host: + type: string + description: Server hostname + port: + description: An array containing the port numbers configured to be used by NodeBB processes + oneOf: + - type: array + items: + oneOf: + - type: string + - type: number + - type: string + - type: number + nodeCount: + type: number + description: The number of NodeBB application processes currently running + timeout: + type: number + ip: + type: string + loggedIn: + type: boolean + relative_path: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/development/logger.yaml b/public/openapi/api/admin/development/logger.yaml new file mode 100644 index 000000000000..bc02dc6faf43 --- /dev/null +++ b/public/openapi/api/admin/development/logger.yaml @@ -0,0 +1,11 @@ +get: + tags: + - admin + summary: Get system logger settings + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/extend/plugins.yaml b/public/openapi/api/admin/extend/plugins.yaml new file mode 100644 index 000000000000..cfa4bd39b859 --- /dev/null +++ b/public/openapi/api/admin/extend/plugins.yaml @@ -0,0 +1,204 @@ +get: + tags: + - admin + summary: Get system plugin settings + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + installed: + type: array + items: + type: object + properties: + latest: + type: string + description: + type: string + name: + type: string + updated: + type: string + url: + type: string + numInstalls: + type: number + isCompatible: + type: boolean + id: + type: string + installed: + type: boolean + active: + type: boolean + isTheme: + type: boolean + error: + type: boolean + version: + type: string + license: + type: object + properties: + name: + type: string + text: + type: string + nullable: true + outdated: + type: boolean + settingsRoute: + type: string + required: + - latest + - description + - name + - id + - installed + - active + - isTheme + - error + - version + - license + - outdated + installedCount: + type: number + activeCount: + type: number + inactiveCount: + type: number + upgradeCount: + type: number + download: + type: array + items: + type: object + properties: + name: + type: string + updated: + type: string + description: + type: string + latest: + type: string + url: + type: string + numInstalls: + type: number + isCompatible: + type: boolean + id: + type: string + installed: + type: boolean + active: + type: boolean + required: + - name + - updated + - latest + - url + - numInstalls + - isCompatible + - id + - installed + - active + incompatible: + type: array + items: + type: object + properties: + latest: + type: string + description: + type: string + name: + type: string + updated: + type: string + url: + type: string + numInstalls: + type: number + isCompatible: + type: boolean + id: + type: string + installed: + type: boolean + active: + type: boolean + required: + - name + - updated + - latest + - url + - numInstalls + - isCompatible + - id + - installed + - active + trending: + type: array + items: + type: object + properties: + latest: + type: string + description: + type: string + name: + type: string + updated: + type: string + url: + type: string + numInstalls: + type: number + isCompatible: + type: boolean + id: + type: string + installed: + type: boolean + active: + type: boolean + isTheme: + type: boolean + error: + type: boolean + version: + type: string + license: + type: object + properties: + name: + type: string + text: + type: string + nullable: true + outdated: + type: boolean + settingsRoute: + type: string + downloads: + type: number + required: + - latest + - description + - name + - id + - installed + - active + - downloads + submitPluginUsage: + type: number + version: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/extend/rewards.yaml b/public/openapi/api/admin/extend/rewards.yaml new file mode 100644 index 000000000000..fcd9b4b04fc4 --- /dev/null +++ b/public/openapi/api/admin/extend/rewards.yaml @@ -0,0 +1,85 @@ +get: + tags: + - admin + summary: Get rewards settings + responses: + "200": + description: "A JSON object containing rewards and their settings" + content: + application/json: + schema: + allOf: + - type: object + properties: + active: + type: array + items: + type: object + properties: + condition: + type: string + conditional: + type: string + value: + type: number + rid: + type: string + claimable: + type: string + id: + type: string + disabled: + type: boolean + rewards: + type: array + items: + additionalProperties: {} + description: Reward-specific properties + conditions: + type: array + items: + type: object + properties: + name: + type: string + condition: + type: string + conditionals: + type: array + items: + type: object + properties: + name: + type: string + conditional: + type: string + rewards: + type: array + items: + type: object + properties: + rid: + type: string + name: + type: string + inputs: + type: array + items: + type: object + properties: + type: + type: string + name: + type: string + label: + type: string + values: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/extend/widgets.yaml b/public/openapi/api/admin/extend/widgets.yaml new file mode 100644 index 000000000000..90527bf8f051 --- /dev/null +++ b/public/openapi/api/admin/extend/widgets.yaml @@ -0,0 +1,90 @@ +get: + tags: + - admin + summary: Get widget settings + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + templates: + type: array + items: + type: object + properties: + template: + type: string + areas: + type: array + items: + type: object + properties: + name: + type: string + location: + type: string + areas: + type: array + items: + type: object + properties: + name: + type: string + template: + type: string + location: + type: string + data: + type: array + items: + type: object + properties: + widget: + type: string + data: + type: object + properties: + html: + type: string + cid: + type: string + title: + type: string + container: + type: string + groups: + type: array + items: {} + groupsHideFrom: + type: array + items: {} + hide-mobile: + type: string + numTags: + type: string + numUsers: + type: string + text: + type: string + parseAsPost: + type: string + numTopics: + type: string + availableWidgets: + type: array + items: + type: object + properties: + widget: + type: string + name: + type: string + description: + type: string + content: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/groups/csv.yaml b/public/openapi/api/admin/groups/csv.yaml new file mode 100644 index 000000000000..43a5bf8e59b6 --- /dev/null +++ b/public/openapi/api/admin/groups/csv.yaml @@ -0,0 +1,19 @@ +get: + tags: + - admin + summary: Get members of a group (.csv) + parameters: + - in: header + name: referer + schema: + type: string + required: true + example: /admin/manage/groups + responses: + "200": + description: "A CSV file containing all users in the group" + content: + text/csv: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/admin/manage/admins-mods.yaml b/public/openapi/api/admin/manage/admins-mods.yaml new file mode 100644 index 000000000000..c5fdffb30911 --- /dev/null +++ b/public/openapi/api/admin/manage/admins-mods.yaml @@ -0,0 +1,56 @@ +get: + tags: + - admin + summary: Get administrators and moderators + responses: + "200": + description: "A JSON object containing administrators and moderators globally and per-category" + content: + application/json: + schema: + allOf: + - type: object + properties: + admins: + $ref: ../../../components/schemas/GroupObject.yaml#/GroupFullObject + globalMods: + $ref: ../../../components/schemas/GroupObject.yaml#/GroupFullObject + categories: + type: array + items: + type: object + properties: + cid: + type: number + name: + type: string + level: + type: number + example: 0 + icon: + type: string + description: A FontAwesome icon string + parentCid: + type: number + description: The parent category's identifier + color: + type: string + description: A six-character hexadecimal colour code + bgColor: + type: string + description: A six-character hexadecimal colour code + imageClass: + type: string + depth: + type: number + description: The depth of the category relative to the forum root (`0` is root level) + moderators: + type: array + items: + $ref: ../../../components/schemas/UserObject.yaml#/UserObjectSlim + allPrivileges: + type: array + items: + type: string + description: A simple array containing user privilege names (used client-side when giving mod privilege) + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/categories.yaml b/public/openapi/api/admin/manage/categories.yaml new file mode 100644 index 000000000000..a13374c929f4 --- /dev/null +++ b/public/openapi/api/admin/manage/categories.yaml @@ -0,0 +1,92 @@ +get: + tags: + - admin + summary: Get category settings + parameters: + - name: category_id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + category: + allOf: + - $ref: ../../../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + parent: + $ref: ../../../components/schemas/CategoryObject.yaml#/CategoryObject + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + icon: + type: string + selected: + type: boolean + level: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + imageClass: + type: string + required: + - cid + - name + - icon + selectedCategory: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + imageClass: + type: string + selected: + type: boolean + customClasses: + type: array + items: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/categories/analytics.yaml b/public/openapi/api/admin/manage/categories/analytics.yaml new file mode 100644 index 000000000000..e3ce87ad8e30 --- /dev/null +++ b/public/openapi/api/admin/manage/categories/analytics.yaml @@ -0,0 +1,42 @@ +get: + tags: + - admin + summary: Get category anayltics + parameters: + - name: category_id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + name: + type: string + analytics: + type: object + properties: + pageviews:hourly: + type: array + items: + type: number + pageviews:daily: + type: array + items: + type: number + topics:daily: + type: array + items: + type: number + posts:daily: + type: array + items: + type: number + - $ref: ../../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/digest.yaml b/public/openapi/api/admin/manage/digest.yaml new file mode 100644 index 000000000000..6ddfc471e25f --- /dev/null +++ b/public/openapi/api/admin/manage/digest.yaml @@ -0,0 +1,51 @@ +get: + tags: + - admin + summary: Get system digest info/settings + responses: + "200": + description: "A JSON object containing recent digest sends and settings" + content: + application/json: + schema: + allOf: + - type: object + properties: + title: + type: string + delivery: + type: array + items: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + picture: + nullable: true + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` + for the user's auto-generated icon + example: "#f44336" + lastDelivery: + type: string + setting: + type: boolean + default: + type: string + required: + - title + - delivery + - $ref: ../../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/groups.yaml b/public/openapi/api/admin/manage/groups.yaml new file mode 100644 index 000000000000..e6a53336b281 --- /dev/null +++ b/public/openapi/api/admin/manage/groups.yaml @@ -0,0 +1,70 @@ +get: + tags: + - admin + summary: Get user group details + parameters: + - name: name + in: path + required: true + schema: + type: string + example: administrators + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + group: + $ref: ../../../components/schemas/GroupObject.yaml#/GroupFullObject + groupNames: + type: array + items: + type: object + properties: + encodedName: + type: string + displayName: + type: string + selected: + type: boolean + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + icon: + type: string + selected: + type: boolean + level: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + imageClass: + type: string + required: + - cid + - name + - icon + allowPrivateGroups: + type: number + maximumGroupNameLength: + type: number + maximumGroupTitleLength: + type: number + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/privileges.yaml b/public/openapi/api/admin/manage/privileges.yaml new file mode 100644 index 000000000000..c533453912eb --- /dev/null +++ b/public/openapi/api/admin/manage/privileges.yaml @@ -0,0 +1,150 @@ +get: + tags: + - admin + summary: Get category privileges + parameters: + - name: cid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + privileges: + type: object + properties: + labels: + type: object + properties: + users: + type: array + items: + type: object + properties: + name: + type: string + groups: + type: array + items: + type: object + properties: + name: + type: string + keys: + type: object + properties: + users: + type: array + items: + type: string + groups: + type: array + items: + type: string + users: + type: array + items: + type: object + properties: + name: + type: string + nameEscaped: + type: string + privileges: + type: object + additionalProperties: + type: boolean + description: Each privilege will have a key in this object + groups: + type: array + items: + type: object + properties: + name: + type: string + nameEscaped: + type: string + privileges: + type: object + additionalProperties: + type: boolean + description: Each privilege will have a key in this object + isPrivate: + type: boolean + columnCountUser: + type: number + columnCountUserOther: + type: number + columnCountGroup: + type: number + columnCountGroupOther: + type: number + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + icon: + type: string + selected: + type: boolean + level: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + imageClass: + type: string + required: + - cid + - name + - icon + - selected + selectedCategory: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + imageClass: + type: string + selected: + type: boolean + cid: + type: number + description: A category identifier + group: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/registration.yaml b/public/openapi/api/admin/manage/registration.yaml new file mode 100644 index 000000000000..3d7fad448732 --- /dev/null +++ b/public/openapi/api/admin/manage/registration.yaml @@ -0,0 +1,90 @@ +get: + tags: + - admin + summary: Get registration queue/invites + responses: + "200": + description: "A JSON object containing the registration queue and invites" + content: + application/json: + schema: + allOf: + - type: object + properties: + registrationQueueCount: + type: number + users: + type: array + items: + type: object + properties: + username: + type: string + email: + type: string + ip: + type: string + timestampISO: + type: string + usernameEscaped: + type: string + ipMatch: + type: array + items: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + customActions: + type: array + items: + type: object + properties: + title: + type: string + id: + type: string + class: + type: string + icon: + type: string + customHeaders: + type: array + invites: + type: array + items: + type: object + properties: + uid: + type: number + invitations: + type: array + items: + type: object + properties: + email: + type: string + - $ref: ../../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/tags.yaml b/public/openapi/api/admin/manage/tags.yaml new file mode 100644 index 000000000000..d0415b29fbc2 --- /dev/null +++ b/public/openapi/api/admin/manage/tags.yaml @@ -0,0 +1,35 @@ +get: + tags: + - admin + summary: Get tag settings + responses: + "200": + description: "A JSON object containing tag settings" + content: + application/json: + schema: + allOf: + - type: object + properties: + tags: + type: array + items: + type: object + properties: + value: + type: string + description: The tag name + score: + type: number + description: The number of topics containing this tag + valueEscaped: + type: string + color: + type: string + description: Six-character hexadecimal string (with `#` prepended) + example: "#ff0000" + bgColor: + type: string + description: Six-character hexadecimal string (with `#` prepended) + example: "#ff0000" + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/uploads.yaml b/public/openapi/api/admin/manage/uploads.yaml new file mode 100644 index 000000000000..85949a2ddd4e --- /dev/null +++ b/public/openapi/api/admin/manage/uploads.yaml @@ -0,0 +1,57 @@ +get: + tags: + - admin + summary: Get uploaded files + parameters: + - in: query + name: dir + schema: + type: string + description: Path of the folder, relative to `public/uploads/` + example: / + responses: + "200": + description: "A JSON object containing uploaded files" + content: + application/json: + schema: + allOf: + - type: object + properties: + currentFolder: + type: string + description: Path of the folder, relative to `public/uploads/` + showPids: + type: boolean + description: Whether or not the post identifiers should be shown (this is `true` only for `public/uploads/files/`, as that is where post uploads go) + files: + type: array + items: + type: object + properties: + name: + type: string + path: + type: string + description: Path relative to `currentFolder` + url: + type: string + description: Relative URL ready to be combined with `config.relative_path` on the client-side or templates + fileCount: + type: number + description: For directories, the number of files inside + size: + type: number + description: The size of the file/directory + sizeHumanReadable: + type: string + isDirectory: + type: boolean + isFile: + type: boolean + mtime: + type: number + description: Last modified time of the file, down to the microsecond (expressed as a UNIX timestamp) + - $ref: ../../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users.yaml b/public/openapi/api/admin/manage/users.yaml new file mode 100644 index 000000000000..5248bb4d5226 --- /dev/null +++ b/public/openapi/api/admin/manage/users.yaml @@ -0,0 +1,35 @@ +get: + tags: + - admin + summary: Get users + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + users: + type: array + items: + $ref: ../../../components/schemas/UserObject.yaml#/UserObjectACP + page: + type: number + pageCount: + type: number + resultsPerPage: + type: number + latest: + type: boolean + search_display: + type: string + requireEmailConfirmation: + type: number + inviteOnly: + type: boolean + adminInviteOnly: + type: boolean + - $ref: ../../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/banned.yaml b/public/openapi/api/admin/manage/users/banned.yaml new file mode 100644 index 000000000000..8c0d42a95478 --- /dev/null +++ b/public/openapi/api/admin/manage/users/banned.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get banned users + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/flagged.yaml b/public/openapi/api/admin/manage/users/flagged.yaml new file mode 100644 index 000000000000..058e9f480e9b --- /dev/null +++ b/public/openapi/api/admin/manage/users/flagged.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get flagged users + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/inactive.yaml b/public/openapi/api/admin/manage/users/inactive.yaml new file mode 100644 index 000000000000..60c01f8eb904 --- /dev/null +++ b/public/openapi/api/admin/manage/users/inactive.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get inactive users + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/latest.yaml b/public/openapi/api/admin/manage/users/latest.yaml new file mode 100644 index 000000000000..b965d0c4c296 --- /dev/null +++ b/public/openapi/api/admin/manage/users/latest.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get latest users + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/most-reputation.yaml b/public/openapi/api/admin/manage/users/most-reputation.yaml new file mode 100644 index 000000000000..81758e8d60fe --- /dev/null +++ b/public/openapi/api/admin/manage/users/most-reputation.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get users with the most reputation + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/no-posts.yaml b/public/openapi/api/admin/manage/users/no-posts.yaml new file mode 100644 index 000000000000..4d0e85b33742 --- /dev/null +++ b/public/openapi/api/admin/manage/users/no-posts.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get users with no posts + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/not-validated.yaml b/public/openapi/api/admin/manage/users/not-validated.yaml new file mode 100644 index 000000000000..2a2e6fd29a91 --- /dev/null +++ b/public/openapi/api/admin/manage/users/not-validated.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get non-verified users + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/search.yaml b/public/openapi/api/admin/manage/users/search.yaml new file mode 100644 index 000000000000..bb5c8d7eaa37 --- /dev/null +++ b/public/openapi/api/admin/manage/users/search.yaml @@ -0,0 +1,39 @@ +get: + tags: + - admin + summary: Get users via search term + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + search_display: + type: string + matchCount: + type: number + query: + type: string + uidQuery: + type: string + usernameQuery: + type: string + emailQuery: + type: string + ipQuery: + type: string + pageCount: + type: number + resultsPerPage: + type: number + timing: + type: number + users: + type: array + items: + $ref: ../../../../components/schemas/UserObject.yaml#/UserObjectACP + - $ref: ../../../../components/schemas/CommonProps.yaml#/CommonProps + - $ref: ../../../../components/schemas/Pagination.yaml#/Pagination \ No newline at end of file diff --git a/public/openapi/api/admin/manage/users/top-posters.yaml b/public/openapi/api/admin/manage/users/top-posters.yaml new file mode 100644 index 000000000000..41c11599d5c5 --- /dev/null +++ b/public/openapi/api/admin/manage/users/top-posters.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get users with the most posts + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" \ No newline at end of file diff --git a/public/openapi/api/admin/settings.yaml b/public/openapi/api/admin/settings.yaml new file mode 100644 index 000000000000..3b8016a349df --- /dev/null +++ b/public/openapi/api/admin/settings.yaml @@ -0,0 +1,24 @@ +get: + tags: + - admin + summary: Get system settings + parameters: + - name: term + in: path + required: true + schema: + type: string + example: general + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: {} + additionalProperties: + type: object + description: Most of the settings pages have their values loaded on the client-side, so the settings are not exposed server-side. + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/settings/homepage.yaml b/public/openapi/api/admin/settings/homepage.yaml new file mode 100644 index 000000000000..3225629c37a2 --- /dev/null +++ b/public/openapi/api/admin/settings/homepage.yaml @@ -0,0 +1,23 @@ +get: + tags: + - admin + summary: Get homepage settings + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + routes: + type: array + items: + type: object + properties: + route: + type: string + name: + type: string + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/settings/languages.yaml b/public/openapi/api/admin/settings/languages.yaml new file mode 100644 index 000000000000..64b1e6b54e3d --- /dev/null +++ b/public/openapi/api/admin/settings/languages.yaml @@ -0,0 +1,35 @@ +get: + tags: + - admin + summary: Get language settings + responses: + "200": + description: A JSON object containing available languages and settings + content: + application/json: + schema: + allOf: + - type: object + properties: + languages: + type: array + items: + type: object + properties: + name: + type: string + description: Localised name of the language + code: + type: string + description: A language code (similar to ISO-639) + dir: + type: string + description: Directionality of the language + enum: [ltr, rtl] + selected: + type: boolean + description: Denotes the currently selected default system language on the forum + autoDetectLang: + type: integer + description: Whether the forum will attempt to guess language based on browser's `Accept-Language` header + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/settings/navigation.yaml b/public/openapi/api/admin/settings/navigation.yaml new file mode 100644 index 000000000000..9f75f9aa28c2 --- /dev/null +++ b/public/openapi/api/admin/settings/navigation.yaml @@ -0,0 +1,107 @@ +get: + tags: + - admin + summary: Get navigation bar settings + responses: + "200": + description: A JSON object containing navigation settings + content: + application/json: + schema: + allOf: + - type: object + properties: + enabled: + type: array + items: + type: object + properties: + route: + type: string + description: Relative URL to the page the navigation item goes to + title: + type: string + description: Tooltip text + enabled: + type: boolean + iconClass: + type: string + description: A FontAwesome icon string + textClass: + type: string + description: HTML class applied to the text label for this navigation item + text: + type: string + description: Label text for this navigation item + order: + type: integer + description: Ordinality of this item, lower value appears earlier + groups: + type: array + items: + type: object + properties: + displayName: + type: string + selected: + type: boolean + index: + type: integer + description: Seemingly identical to order, but an integer instead of a string + selected: + type: boolean + available: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID that will be added to the navigation element's `id` property in the DOM + route: + type: string + description: Relative URL to the page the navigation item goes to + title: + type: string + description: Tooltip text + enabled: + type: boolean + iconClass: + type: string + description: A FontAwesome icon string + textClass: + type: string + description: HTML class applied to the text label for this navigation item + text: + type: string + description: Label text for this navigation item + core: + type: boolean + description: Whether the navigation item is provided by core or not (a plugin) + groups: + type: array + items: + type: object + properties: + name: + type: string + displayName: + type: string + properties: + type: object + properties: + targetBlank: + type: boolean + groups: + type: array + items: + type: object + properties: + name: + type: string + displayName: + type: string + navigation: + type: array + description: A clone of `enabled` + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/settings/social.yaml b/public/openapi/api/admin/settings/social.yaml new file mode 100644 index 000000000000..7d32a1706449 --- /dev/null +++ b/public/openapi/api/admin/settings/social.yaml @@ -0,0 +1,28 @@ +get: + tags: + - admin + summary: Get post social sharing settings + responses: + "200": + description: "A JSON object containing post social sharing settings" + content: + application/json: + schema: + allOf: + - type: object + properties: + posts: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + class: + type: string + description: A FontAwesome icon string + activated: + type: boolean + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/admin/upload/file.yaml b/public/openapi/api/admin/upload/file.yaml new file mode 100644 index 000000000000..7d600b76c4c2 --- /dev/null +++ b/public/openapi/api/admin/upload/file.yaml @@ -0,0 +1,35 @@ +post: + tags: + - admin + summary: Upload a file + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + folder: + type: string + description: The folder to upload the files to (relative to `public/uploads/`) + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "File uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded file for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/uploadDefaultAvatar.yaml b/public/openapi/api/admin/uploadDefaultAvatar.yaml new file mode 100644 index 000000000000..1f725c8c0f82 --- /dev/null +++ b/public/openapi/api/admin/uploadDefaultAvatar.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload default avatar + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/uploadMaskableIcon.yaml b/public/openapi/api/admin/uploadMaskableIcon.yaml new file mode 100644 index 000000000000..94640a74fac7 --- /dev/null +++ b/public/openapi/api/admin/uploadMaskableIcon.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload Maskable Icon + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded logo for the Maskable Icon entry for PWA / A2HS \ No newline at end of file diff --git a/public/openapi/api/admin/uploadOgImage.yaml b/public/openapi/api/admin/uploadOgImage.yaml new file mode 100644 index 000000000000..9561a14b52f8 --- /dev/null +++ b/public/openapi/api/admin/uploadOgImage.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload site-wide Open Graph Image + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/uploadTouchIcon.yaml b/public/openapi/api/admin/uploadTouchIcon.yaml new file mode 100644 index 000000000000..d0c63ff107ee --- /dev/null +++ b/public/openapi/api/admin/uploadTouchIcon.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload Touch Icon + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded logo for the Homescreen/Touch Icon to enable PWA \ No newline at end of file diff --git a/public/openapi/api/admin/uploadfavicon.yaml b/public/openapi/api/admin/uploadfavicon.yaml new file mode 100644 index 000000000000..d53b593fa4f5 --- /dev/null +++ b/public/openapi/api/admin/uploadfavicon.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload favicon + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/uploadlogo.yaml b/public/openapi/api/admin/uploadlogo.yaml new file mode 100644 index 000000000000..ef1ddd8f7150 --- /dev/null +++ b/public/openapi/api/admin/uploadlogo.yaml @@ -0,0 +1,32 @@ +post: + tags: + - admin + summary: Upload site logo + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side \ No newline at end of file diff --git a/public/openapi/api/admin/users/csv.yaml b/public/openapi/api/admin/users/csv.yaml new file mode 100644 index 000000000000..244a88beea38 --- /dev/null +++ b/public/openapi/api/admin/users/csv.yaml @@ -0,0 +1,19 @@ +get: + tags: + - admin + summary: Get users export (.csv) + parameters: + - in: header + name: referer + schema: + type: string + required: true + example: /admin/manage/users + responses: + "200": + description: "A CSV file containing all registered users" + content: + text/csv: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/categories.yaml b/public/openapi/api/categories.yaml new file mode 100644 index 000000000000..cfa3cc972466 --- /dev/null +++ b/public/openapi/api/categories.yaml @@ -0,0 +1,208 @@ +get: + tags: + - categories + summary: Get a list of categories + description: > + This route retrieve the list of categories currently available to the + accessing user. It doesn't necessarily mean that the user can *enter* + the category, as that is a separate privilege. Specifically, this route + will return all categories that grant the calling user the "Find + Category" privilege. + + + Subcategories are also returned, nested under a category's `children` property. + responses: + "200": + description: A list of category objectscurrently available to the accessing user + content: + application/json: + schema: + allOf: + - type: object + properties: + title: + description: The page title + type: string + categories: + description: A collection of category data objects + type: array + items: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + children: + type: array + items: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + children: + type: array + items: + $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + parent: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + posts: + type: array + items: + type: object + properties: + pid: + type: number + timestamp: + type: number + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to + users without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction + with `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + cid: + type: number + description: A category identifier + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + topic: + type: object + properties: + slug: + type: string + title: + type: string + imageClass: + type: string + timesClicked: + type: number + posts: + type: array + items: + type: object + properties: + pid: + type: number + timestamp: + type: number + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + cid: + type: number + description: A category identifier + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + topic: + type: object + properties: + slug: + type: string + title: + type: string + teaser: + type: object + properties: + url: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + pid: + type: number + topic: + type: object + properties: + slug: + type: string + title: + type: string + imageClass: + type: string + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/categories/moderators.yaml b/public/openapi/api/categories/moderators.yaml new file mode 100644 index 000000000000..b1116115f00d --- /dev/null +++ b/public/openapi/api/categories/moderators.yaml @@ -0,0 +1,30 @@ +get: + tags: + - categories + summary: Get mods for a category + description: > + This route returns an array of uids that correspond to the moderators + for the category in question. + parameters: + - name: cid + description: The category identifier for the category you wish to look up + in: path + required: true + schema: + type: number + example: 1 + responses: + "200": + description: An array of moderators for the requested category + content: + application/json: + schema: + type: object + properties: + moderators: + type: array + example: + moderators: + - 1 + - 2 + - 3 \ No newline at end of file diff --git a/public/openapi/api/category.yaml b/public/openapi/api/category.yaml new file mode 100644 index 000000000000..dfe88aa950b9 --- /dev/null +++ b/public/openapi/api/category.yaml @@ -0,0 +1,97 @@ +get: + tags: + - categories + summary: Get a single category + description: This route retrieves a single category's data, along with its children and the topics created inside of the category. + parameters: + - name: category_id + in: path + required: true + schema: + type: string + example: 1 + - name: slug + description: This parameter is not required. If omitted, the request will be automatically redirected with the proper category slug. + in: path + required: true + schema: + type: string + example: test + - name: topic_index + description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + children: + type: array + items: + $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + topics: + type: array + items: + $ref: ../components/schemas/TopicObject.yaml#/TopicObject + nextStart: + type: number + isWatched: + type: boolean + isNotWatched: + type: boolean + isIgnored: + type: boolean + title: + type: string + privileges: + type: object + properties: + topics:create: + type: boolean + topics:read: + type: boolean + topics:tag: + type: boolean + read: + type: boolean + cid: + type: string + uid: + type: number + description: A user identifier + editable: + type: boolean + view_deleted: + type: boolean + isAdminOrMod: + type: boolean + showSelect: + type: boolean + showTopicTools: + type: boolean + topicIndex: + type: number + rssFeedUrl: + type: string + feeds:disableRSS: + type: number + reputation:disabled: + type: number + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/category/cid.yaml b/public/openapi/api/category/cid.yaml new file mode 100644 index 000000000000..98fd0d4e34c9 --- /dev/null +++ b/public/openapi/api/category/cid.yaml @@ -0,0 +1,63 @@ +get: + tags: + - shorthand + summary: Get category data + parameters: + - name: id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "A JSON object containing category data" + content: + application/json: + schema: + type: object + properties: + cid: + type: number + name: + type: number + description: + type: string + descriptionParsed: + type: string + icon: + type: string + bgColor: + type: string + color: + type: string + slug: + type: string + parentCid: + type: number + topic_count: + type: number + post_count: + type: number + disabled: + type: number + order: + type: number + link: + type: string + numRecentReplies: + type: number + class: + type: string + imageClass: + type: string + isSection: + type: number + totalPostCount: + type: number + totalTopicCount: + type: number + minTags: + type: number + maxTags: + type: number \ No newline at end of file diff --git a/public/openapi/api/chats.yaml b/public/openapi/api/chats.yaml new file mode 100644 index 000000000000..0780b774cb27 --- /dev/null +++ b/public/openapi/api/chats.yaml @@ -0,0 +1,20 @@ +get: + tags: + - shorthand + summary: Access a chat room + description: Redirects a request to the proper chat page URL + parameters: + - name: roomid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "Chat identifier resolved" + content: + text/plain: + schema: + type: string + description: A relative path to the canonical URL for that chat page \ No newline at end of file diff --git a/public/openapi/api/config.yaml b/public/openapi/api/config.yaml new file mode 100644 index 000000000000..3e91fd759b50 --- /dev/null +++ b/public/openapi/api/config.yaml @@ -0,0 +1,135 @@ +get: + tags: + - home + summary: Get forum settings + description: This route retrieves forum settings and user-specific settings for client-side options on the forum. + responses: + "200": + description: "" + content: + application/json: + schema: + type: object + properties: + relative_path: + type: string + upload_url: + type: string + assetBaseUrl: + type: string + siteTitle: + type: string + browserTitle: + type: string + titleLayout: + type: string + showSiteTitle: + type: boolean + minimumTitleLength: + type: number + maximumTitleLength: + type: number + minimumPostLength: + type: number + maximumPostLength: + type: number + minimumTagsPerTopic: + type: number + maximumTagsPerTopic: + type: number + minimumTagLength: + type: number + maximumTagLength: + type: number + useOutgoingLinksPage: + type: boolean + allowGuestHandles: + type: boolean + allowTopicsThumbnail: + type: boolean + usePagination: + type: boolean + disableChat: + type: boolean + disableChatMessageEditing: + type: boolean + maximumChatMessageLength: + type: number + socketioTransports: + type: array + items: + type: string + socketioOrigins: + type: string + websocketAddress: + type: string + maxReconnectionAttempts: + type: number + reconnectionDelay: + type: number + topicsPerPage: + type: number + postsPerPage: + type: number + maximumFileSize: + type: number + theme:id: + type: string + theme:src: + type: string + defaultLang: + type: string + userLang: + type: string + loggedIn: + type: boolean + uid: + type: number + description: A user identifier + cache-buster: + type: string + requireEmailConfirmation: + type: boolean + topicPostSort: + type: string + categoryTopicSort: + type: string + csrf_token: + type: string + searchEnabled: + type: boolean + bootswatchSkin: + type: string + enablePostHistory: + type: boolean + timeagoCutoff: + type: number + timeagoCodes: + type: array + items: + type: string + cookies: + type: object + properties: + enabled: + type: boolean + message: + type: string + dismiss: + type: string + link: + type: string + link_url: + type: string + acpLang: + type: string + openOutgoingLinksInNewTab: + type: boolean + topicSearchEnabled: + type: boolean + hideSubCategories: + type: boolean + hideCategoryLastPost: + type: boolean + enableQuickReply: + type: boolean \ No newline at end of file diff --git a/public/openapi/api/email/unsubscribe.yaml b/public/openapi/api/email/unsubscribe.yaml new file mode 100644 index 000000000000..71c02c880964 --- /dev/null +++ b/public/openapi/api/email/unsubscribe.yaml @@ -0,0 +1,17 @@ +# TODO: Need GET route here as well +post: + tags: + - emails + summary: Unsubscribe user from email type + parameters: + - name: token + in: path + required: true + schema: + type: string + example: testToken + responses: + "200": + description: "Successfully unsubscribed" + "500": + description: "Server-side error (likely token verification failure)" \ No newline at end of file diff --git a/public/openapi/api/flags.yaml b/public/openapi/api/flags.yaml new file mode 100644 index 000000000000..1aa613bd889b --- /dev/null +++ b/public/openapi/api/flags.yaml @@ -0,0 +1,220 @@ +get: + tags: + - flags + summary: /api/flags/{flagId} + parameters: + - name: flagId + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + state: + type: string + flagId: + type: number + type: + type: string + targetId: + type: number + targetUid: + type: number + datetime: + type: number + datetimeISO: + type: string + target_readable: + type: string + target: + type: object + properties: {} + additionalProperties: + description: Properties change depending on the target type (user, post, etc.) + assignee: + type: number + nullable: true + history: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + fields: + type: object + additionalProperties: {} + meta: + type: array + items: + type: object + properties: + key: + type: string + value: + type: string + labelClass: + type: string + enum: ['default', 'primary', 'success', 'info', 'danger'] + required: + - key + datetime: + type: number + datetimeISO: + type: string + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + required: + - uid + - datetime + - datetimeISO + - user + notes: + type: array + items: + type: object + properties: + uid: + type: number + content: + type: string + datetime: + type: number + datetimeISO: + type: string + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + reports: + type: array + items: + type: object + properties: + value: + type: string + timestamp: + type: number + timestampISO: + type: string + reporter: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + reputation: + type: number + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` for + the user's auto-generated icon + example: "#f44336" + type_path: + type: string + assignees: + type: array + items: + $ref: ../components/schemas/UserObject.yaml#/UserObject + type_bool: + type: object + properties: + post: + type: boolean + user: + type: boolean + empty: + type: boolean + title: + type: string + categories: + type: object + additionalProperties: + type: string + filters: + type: object + properties: + page: + type: number + perPage: + type: number + privileges: + type: object + properties: {} + additionalProperties: + description: "A list of global and admin privileges, and whether the calling user has (or has inherited) them" + type: boolean + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/groups.yaml b/public/openapi/api/groups.yaml new file mode 100644 index 000000000000..f0c6a3ca18ef --- /dev/null +++ b/public/openapi/api/groups.yaml @@ -0,0 +1,34 @@ +get: + tags: + - groups + summary: Get user group details + parameters: + - name: slug + in: path + required: true + schema: + type: string + example: administrators + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + title: + type: string + group: + $ref: ../components/schemas/GroupObject.yaml#/GroupFullObject + posts: + $ref: ../components/schemas/PostsObject.yaml#/PostsObject + isAdmin: + type: boolean + isGlobalMod: + type: boolean + allowPrivateGroups: + type: number + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/groups/members.yaml b/public/openapi/api/groups/members.yaml new file mode 100644 index 000000000000..593c019284ee --- /dev/null +++ b/public/openapi/api/groups/members.yaml @@ -0,0 +1,25 @@ +get: + tags: + - groups + summary: Get user group members + parameters: + - name: slug + in: path + required: true + schema: + type: string + example: administrators + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + users: + type: array + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps diff --git a/public/openapi/api/index.yaml b/public/openapi/api/index.yaml new file mode 100644 index 000000000000..4b29a1dc99aa --- /dev/null +++ b/public/openapi/api/index.yaml @@ -0,0 +1,202 @@ +get: + tags: + - home + description: > + This route is used to populate the homepage of NodeBB. It is the main + access point of the forum, and shows a list of categories for navigation + purposes. + summary: Get forum index data + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + title: + type: string + description: The page title + categories: + description: A collection of category data objects + type: array + items: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + children: + type: array + items: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + children: + type: array + items: + $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + parent: + allOf: + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - type: object + properties: + tagWhitelist: + type: array + items: + type: string + unread-class: + type: string + posts: + type: array + items: + type: object + properties: + pid: + type: number + timestamp: + type: number + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to + users without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction + with `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + cid: + type: number + description: A category identifier + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + topic: + type: object + properties: + slug: + type: string + title: + type: string + imageClass: + type: string + timesClicked: + type: number + posts: + type: array + items: + type: object + properties: + pid: + type: number + timestamp: + type: number + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + cid: + type: number + description: A category identifier + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + topic: + type: object + properties: + slug: + type: string + title: + type: string + teaser: + type: object + properties: + url: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + pid: + type: number + topic: + type: object + properties: + slug: + type: string + title: + type: string + imageClass: + type: string + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/ip-blacklist.yaml b/public/openapi/api/ip-blacklist.yaml new file mode 100644 index 000000000000..332d2fc1d67d --- /dev/null +++ b/public/openapi/api/ip-blacklist.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get IP blacklist settings + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" \ No newline at end of file diff --git a/public/openapi/api/login.yaml b/public/openapi/api/login.yaml new file mode 100644 index 000000000000..a480ef74b9bb --- /dev/null +++ b/public/openapi/api/login.yaml @@ -0,0 +1,58 @@ +get: + tags: + - authentication + summary: /api/login + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + loginFormEntry: + type: array + items: + type: object + properties: + label: + type: string + description: A label for the added block + html: + type: string + description: HTML to render on the login page + styleName: + type: string + description: Custom identifier (value is added to `input[id]` and `label[for]`) + alternate_logins: + type: boolean + authentication: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + callbackURL: + type: string + icon: + type: string + scope: + type: string + prompt: + type: string + allowRegistration: + type: boolean + allowLoginWith: + type: string + title: + type: string + allowPasswordReset: + type: boolean + allowLocalLogin: + type: boolean + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/me.yaml b/public/openapi/api/me.yaml new file mode 100644 index 000000000000..6c3febadfd01 --- /dev/null +++ b/public/openapi/api/me.yaml @@ -0,0 +1,10 @@ +get: + tags: + - shorthand + summary: Access your own profile's sub-pages + description: >- + This shorthand is useful if you want to link to pages in your own account profile, but do not want (or have) the `userslug`. It is also especially useful as a + means to instruct users on how to do things, as you can easily redirect them to their own profile pages. + responses: + "200": + description: "Canonical URL to your requested profile page" \ No newline at end of file diff --git a/public/openapi/api/notifications.yaml b/public/openapi/api/notifications.yaml new file mode 100644 index 000000000000..84d3e56c517c --- /dev/null +++ b/public/openapi/api/notifications.yaml @@ -0,0 +1,109 @@ +get: + tags: + - notifications + summary: Get notifications + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + notifications: + type: array + items: + type: object + properties: + bodyShort: + type: string + path: + type: string + nid: + type: string + from: + type: number + importance: + type: number + datetime: + type: number + datetimeISO: + type: string + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + nullable: true + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + image: + type: string + nullable: true + read: + type: boolean + readClass: + type: string + filters: + type: array + items: + type: object + additionalProperties: {} + regularFilters: + type: array + items: + type: object + properties: + name: + type: string + filter: + type: string + selected: + type: boolean + required: + - name + - filter + moderatorFilters: + type: array + items: + type: object + properties: + name: + type: string + filter: + type: string + selectedFilter: + type: object + properties: + name: + type: string + filter: + type: string + selected: + type: boolean + title: + type: string + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/popular.yaml b/public/openapi/api/popular.yaml new file mode 100644 index 000000000000..e5e379b683df --- /dev/null +++ b/public/openapi/api/popular.yaml @@ -0,0 +1,137 @@ +get: + tags: + - topics + summary: Get popular topics + description: Returns a list of topics sorted by most replies. In an event of a + tie breaker, the topic with the most views. Can be filtered by All Time, + Day, Week, or Month. + responses: + "200": + description: An array of topic objects sorted by most replies and views. + content: + application/json: + schema: + allOf: + - type: object + properties: + nextStart: + type: number + topicCount: + type: number + topics: + type: array + items: + $ref: ../components/schemas/TopicObject.yaml#/TopicObject + tids: + type: array + items: + type: number + canPost: + type: boolean + showSelect: + type: boolean + showTopicTools: + type: boolean + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCategory: + type: object + properties: + icon: + type: string + name: + type: string + bgColor: + type: string + nullable: true + selectedCids: + type: array + items: + type: number + feeds:disableRSS: + type: number + rssFeedUrl: + type: string + title: + type: string + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + terms: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + selectedTerm: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/post-queue.yaml b/public/openapi/api/post-queue.yaml new file mode 100644 index 000000000000..794f7e1f15b3 --- /dev/null +++ b/public/openapi/api/post-queue.yaml @@ -0,0 +1,180 @@ +get: + tags: + - admin + summary: Get flag data + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + title: + type: string + allCategories: + type: array + items: + type: object + properties: + bgColor: + type: string + cid: + type: number + color: + type: string + disabled: + type: number + disabledClass: + type: boolean + icon: + type: string + imageClass: + type: string + level: + type: string + link: + type: string + name: + type: string + parentCid: + type: number + slug: + type: string + posts: + type: array + items: + allOf: + - type: object + properties: + id: + type: string + uid: + type: number + description: A user identifier + type: + type: string + data: + type: object + properties: + title: + type: string + content: + type: string + thumb: + type: string + cid: + oneOf: + - type: number + - type: string + tags: + type: array + items: {} + uid: + type: number + description: A user identifier + req: + type: object + properties: + uid: + type: number + description: A user identifier + ip: + type: string + host: + type: string + protocol: + type: string + secure: + type: boolean + url: + type: string + path: + type: string + headers: + type: object + properties: + x-real-ip: + type: string + x-forwarded-for: + type: string + x-forwarded-proto: + type: string + host: + type: string + x-nginx-proxy: + type: string + connection: + type: string + accept: + type: string + user-agent: + type: string + sec-fetch-site: + type: string + sec-fetch-mode: + type: string + referer: + type: string + accept-encoding: + type: string + accept-language: + type: string + cookie: + type: string + timestamp: + type: number + fromQueue: + type: boolean + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + rawContent: + type: string + tid: + type: number + description: A topic identifier + toPid: + nullable: true + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + topic: + type: object + properties: + cid: + type: number + title: + type: string + titleRaw: + type: string + - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/post.yaml b/public/openapi/api/post.yaml new file mode 100644 index 000000000000..6d294895d5a7 --- /dev/null +++ b/public/openapi/api/post.yaml @@ -0,0 +1,19 @@ +get: + tags: + - shorthand + summary: Access a specific post + description: This route comes in handy when all you have is the `pid`, and you want to redirect users to the canonical URL for the topic, with the appropriate topic slug and post index. + parameters: + - name: pid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "Canonical URL of topic" + content: + text/plain: + schema: + type: string \ No newline at end of file diff --git a/public/openapi/api/post/pid.yaml b/public/openapi/api/post/pid.yaml new file mode 100644 index 000000000000..527ee4ec29c9 --- /dev/null +++ b/public/openapi/api/post/pid.yaml @@ -0,0 +1,56 @@ +get: + tags: + - shorthand + summary: Get post data + parameters: + - name: id + in: path + required: true + schema: + type: number + example: 1 + responses: + "200": + description: "A JSON object containing post data" + content: + application/json: + schema: + type: object + properties: + uid: + type: number + tid: + type: number + timestamp: + type: number + content: + type: string + pid: + type: number + downvotes: + type: number + upvotes: + type: number + bookmarks: + type: number + deleted: + type: number + deleterUid: + type: number + edited: + type: number + votes: + type: number + timestampISO: + type: string + editedISO: + type: string + upvoted: + type: boolean + downvoted: + type: boolean + flagId: + type: number + description: The flag identifier, if this particular post has been flagged before + replies: + type: number \ No newline at end of file diff --git a/public/openapi/api/post/upload.yaml b/public/openapi/api/post/upload.yaml new file mode 100644 index 000000000000..877160d6adb8 --- /dev/null +++ b/public/openapi/api/post/upload.yaml @@ -0,0 +1,59 @@ +post: + tags: + - posts + summary: Upload a file to a specific post + description: Provided by NodeBB core and used mainly by the composer, this route allows you to upload an image or file to a post. + responses: + "200": + description: "" + content: + application/json: + schema: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + text/plain: + schema: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + "403": + description: "" + content: + application/json: + schema: + type: string + example: Forbidden + text/plain: + schema: + type: string + example: Forbidden + "500": + description: "" + content: + application/json: + schema: + type: object + properties: + path: + type: string + error: + type: string + text/plain: + schema: + type: object + properties: + path: + type: string + error: + type: string \ No newline at end of file diff --git a/public/openapi/api/recent.yaml b/public/openapi/api/recent.yaml new file mode 100644 index 000000000000..69b64c1dfd62 --- /dev/null +++ b/public/openapi/api/recent.yaml @@ -0,0 +1,135 @@ +get: + tags: + - topics + summary: Get recent topics + description: Returns a list of topics sorted by timestamp. + responses: + "200": + description: An array of topic objects sorted by timestamp. + content: + application/json: + schema: + allOf: + - type: object + properties: + nextStart: + type: number + topicCount: + type: number + topics: + type: array + items: + $ref: ../components/schemas/TopicObject.yaml#/TopicObject + tids: + type: array + items: + type: number + canPost: + type: boolean + showSelect: + type: boolean + showTopicTools: + type: boolean + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCategory: + type: object + properties: + icon: + type: string + name: + type: string + bgColor: + type: string + nullable: true + selectedCids: + type: array + items: + type: number + feeds:disableRSS: + type: number + rssFeedUrl: + type: string + title: + type: string + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + terms: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + selectedTerm: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/recent/posts.yaml b/public/openapi/api/recent/posts.yaml new file mode 100644 index 000000000000..617ac3a615b7 --- /dev/null +++ b/public/openapi/api/recent/posts.yaml @@ -0,0 +1,18 @@ +get: + tags: + - posts + summary: Get recent posts + parameters: + - name: term + in: path + required: true + schema: + type: string + example: daily + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject \ No newline at end of file diff --git a/public/openapi/api/register.yaml b/public/openapi/api/register.yaml new file mode 100644 index 000000000000..199b496e0301 --- /dev/null +++ b/public/openapi/api/register.yaml @@ -0,0 +1,81 @@ +get: + tags: + - authentication + summary: /api/register + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + register_window:spansize: + type: string + alternate_logins: + type: boolean + authentication: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + callbackURL: + type: string + icon: + type: string + scope: + type: string + prompt: + type: string + minimumUsernameLength: + type: number + maximumUsernameLength: + type: number + minimumPasswordLength: + type: number + minimumPasswordStrength: + type: number + regFormEntry: + type: array + items: + type: object + properties: + label: + type: string + html: + type: string + styleName: + type: string + title: + type: string + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps + # /api/register/complete: + # get: + # tags: + # - authentication + # summary: /api/register/complete + # responses: + # "200": + # description: "" + # content: + # application/json: + # schema: + # allOf: + # - type: object + # properties: + # title: + # type: string + # errors: + # type: array + # items: {} + # sections: + # type: array + # items: + # type: string + # - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/registration-queue.yaml b/public/openapi/api/registration-queue.yaml new file mode 100644 index 000000000000..dc44e9d35379 --- /dev/null +++ b/public/openapi/api/registration-queue.yaml @@ -0,0 +1,7 @@ +get: + tags: + - admin + summary: Get registration queue + responses: + "418": + description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" \ No newline at end of file diff --git a/public/openapi/api/reset.yaml b/public/openapi/api/reset.yaml new file mode 100644 index 000000000000..986bf6c3aa36 --- /dev/null +++ b/public/openapi/api/reset.yaml @@ -0,0 +1,32 @@ +get: + tags: + - authentication + summary: Get user password reset (step 2) + parameters: + - name: code + in: path + required: true + schema: + type: string + example: testCode + responses: + "200": + description: "A JSON object containing the 2nd step of the user password reset flow" + content: + application/json: + schema: + allOf: + - type: object + properties: + valid: + type: boolean + code: + type: string + minimumPasswordLength: + type: number + minimumPasswordStrength: + type: number + title: + type: string + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/search.yaml b/public/openapi/api/search.yaml new file mode 100644 index 000000000000..b1c7984c68a2 --- /dev/null +++ b/public/openapi/api/search.yaml @@ -0,0 +1,77 @@ +get: + tags: + - search + summary: Get search results + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + posts: + $ref: ../components/schemas/PostsObject.yaml#/PostsObject + matchCount: + type: number + pageCount: + type: number + time: + type: string + multiplePages: + type: boolean + search_query: + type: string + term: + type: string + categories: + type: array + items: + type: object + properties: + value: + oneOf: + - type: string + - type: number + text: + type: string + categoriesCount: + type: number + expandSearch: + type: boolean + showAsPosts: + type: boolean + showAsTopics: + type: boolean + title: + type: string + searchDefaultSortBy: + type: string + privileges: + type: object + properties: + search:users: + type: boolean + search:content: + type: boolean + search:tags: + type: boolean + required: + - posts + - matchCount + - pageCount + - time + - multiplePages + - search_query + - categories + - categoriesCount + - expandSearch + - showAsPosts + - showAsTopics + - title + - searchDefaultSortBy + - permissions + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/self.yaml b/public/openapi/api/self.yaml new file mode 100644 index 000000000000..e3979709cfbf --- /dev/null +++ b/public/openapi/api/self.yaml @@ -0,0 +1,12 @@ +get: + tags: + - shorthand + summary: Access your profile data + description: This shorthand returns the data for the logged in user, identical to the data returned at this route /user/ + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../components/schemas/UserObject.yaml#/UserObjectFull \ No newline at end of file diff --git a/public/openapi/api/tags.yaml b/public/openapi/api/tags.yaml new file mode 100644 index 000000000000..b3ac785697d6 --- /dev/null +++ b/public/openapi/api/tags.yaml @@ -0,0 +1,276 @@ +get: + tags: + - tags + summary: Get tag data + description: Returns a list of topics that are tagged with {tag} + parameters: + - name: tag + description: The tag used to retrieve the topics + in: path + required: true + schema: + type: string + example: test + - name: page + description: Page number used in pagination + in: query + required: false + schema: + type: number + example: '' + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + topics: + type: array + description: An array of topics that are all tagged with {tag} + items: + type: object + properties: + tid: + type: number + description: A topic identifier + uid: + type: number + description: A user identifier + cid: + type: number + description: A category identifier + mainPid: + type: number + description: The post id of the first post in this topic (also called the + "original post") + title: + type: string + slug: + type: string + timestamp: + type: number + lastposttime: + type: number + postcount: + type: number + viewcount: + type: number + teaserPid: + oneOf: + - type: number + - type: string + deleted: + type: number + locked: + type: number + pinned: + type: number + description: Whether or not this particular topic is pinned to the top of the + category + upvotes: + type: number + downvotes: + type: number + titleRaw: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + lastposttimeISO: + type: string + votes: + type: number + category: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + slug: + type: string + icon: + type: string + image: + nullable: true + imageClass: + nullable: true + type: string + bgColor: + type: string + color: + type: string + disabled: + type: number + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + reputation: + type: number + postcount: + type: number + picture: + nullable: true + type: string + signature: + nullable: true + type: string + banned: + type: number + status: + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + banned_until_readable: + type: string + fullname: + type: string + teaser: + type: object + properties: + pid: + type: number + uid: + type: number + description: A user identifier + timestamp: + type: number + tid: + type: number + description: A topic identifier + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + tags: + type: array + items: + type: object + properties: + value: + type: string + valueEscaped: + type: string + color: + type: string + bgColor: + type: string + score: + type: number + isOwner: + type: boolean + ignored: + type: boolean + unread: + type: boolean + bookmark: + nullable: true + unreplied: + type: boolean + icons: + type: array + items: {} + index: + type: number + thumb: + type: string + isQuestion: + nullable: true + type: number + isSolved: + type: number + tag: + type: string + title: + type: string + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + rssFeedUrl: + type: string + required: + - topics + - tag + - title + - categories + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/top.yaml b/public/openapi/api/top.yaml new file mode 100644 index 000000000000..f7bce5367fe4 --- /dev/null +++ b/public/openapi/api/top.yaml @@ -0,0 +1,148 @@ +get: + tags: + - topics + summary: Get top topics + description: Returns a list of topics sorted by most upvotes. + responses: + "200": + description: An array of topic objects sorted by most upvotes. + content: + application/json: + schema: + allOf: + - type: object + properties: + nextStart: + type: number + topicCount: + type: number + topics: + type: array + items: + $ref: ../components/schemas/TopicObject.yaml#/TopicObject + tids: + type: array + items: + type: number + canPost: + type: boolean + showSelect: + type: boolean + showTopicTools: + type: boolean + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCategory: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + nullable: true + selectedCids: + type: array + items: + type: number + feeds:disableRSS: + type: number + rssFeedUrl: + type: string + title: + type: string + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + terms: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + selectedTerm: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/topic.yaml b/public/openapi/api/topic.yaml new file mode 100644 index 000000000000..cb14ffe6a101 --- /dev/null +++ b/public/openapi/api/topic.yaml @@ -0,0 +1,414 @@ +get: + tags: + - topics + summary: Get topic data + parameters: + - name: topic_id + in: path + required: true + schema: + type: string + example: 1 + - name: slug + description: This parameter is not required. If omitted, the request will be automatically redirected with the proper topic slug. + in: path + required: true + schema: + type: string + example: test-topic + - name: post_index + description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + tid: + type: number + description: A topic identifier + uid: + type: number + description: A user identifier + cid: + type: number + description: A category identifier + title: + type: string + slug: + type: string + timestamp: + type: number + lastposttime: + type: number + postcount: + type: number + viewcount: + type: number + posterCount: + type: number + description: The number of unique users who made a post in this topic + mainPid: + type: number + description: The post id of the first post in this topic (also called the + "original post") + teaserPid: + type: number + nullable: true + upvotes: + type: number + downvotes: + type: number + deleted: + type: number + locked: + type: number + pinned: + type: number + description: Whether or not this particular topic is pinned to the top of the + category + deleterUid: + type: number + titleRaw: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + lastposttimeISO: + type: string + votes: + type: number + tags: + type: array + items: + type: object + properties: + value: + type: string + valueEscaped: + type: string + color: + type: string + bgColor: + type: string + score: + type: number + posts: + type: array + items: + type: object + properties: + pid: + type: number + uid: + type: number + description: A user identifier + tid: + type: number + description: A topic identifier + content: + type: string + timestamp: + type: number + votes: + type: number + deleted: + type: number + upvotes: + type: number + downvotes: + type: number + bookmarks: + type: number + deleterUid: + type: number + edited: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + editedISO: + type: string + index: + type: number + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + reputation: + type: number + postcount: + type: number + topiccount: + type: number + picture: + type: string + nullable: true + signature: + type: string + banned: + type: number + banned:expire: + type: number + status: + type: string + lastonline: + type: number + groupTitle: + nullable: true + type: string + groupTitleArray: + type: array + items: + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + lastonlineISO: + type: string + banned_until: + type: number + banned_until_readable: + type: string + selectedGroups: + type: array + items: + type: object + properties: + name: + type: string + slug: + type: string + labelColor: + type: string + textColor: + type: string + icon: + type: string + userTitle: + type: string + custom_profile_info: + type: array + items: + type: object + properties: + content: + type: string + description: HTML that is injected into `topic.tpl` of themes that support custom profile info + editor: + nullable: true + bookmarked: + type: boolean + upvoted: + type: boolean + downvoted: + type: boolean + replies: + type: object + properties: + hasMore: + type: boolean + users: + type: array + items: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + administrator: + type: boolean + text: + type: string + count: + type: number + selfPost: + type: boolean + display_edit_tools: + type: boolean + display_delete_tools: + type: boolean + display_moderator_tools: + type: boolean + display_move_tools: + type: boolean + display_post_menu: + type: boolean + flagId: + type: number + description: The flag identifier, if this particular post has been flagged before + category: + $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject + tagWhitelist: + type: array + items: + type: string + minTags: + type: number + maxTags: + type: number + thread_tools: + type: array + items: + type: object + properties: + class: + type: string + title: + type: string + icon: + type: string + isFollowing: + type: boolean + isNotFollowing: + type: boolean + isIgnoring: + type: boolean + bookmark: + nullable: true + postSharing: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + class: + type: string + activated: + type: boolean + deleter: + nullable: true + merger: + nullable: true + related: + type: array + items: + $ref: ../components/schemas/TopicObject.yaml#/TopicObject + unreplied: + type: boolean + icons: + type: array + items: + type: string + description: HTML that is rendered by the theme + privileges: + type: object + properties: + topics:reply: + type: boolean + topics:read: + type: boolean + topics:tag: + type: boolean + topics:delete: + type: boolean + posts:edit: + type: boolean + posts:history: + type: boolean + posts:delete: + type: boolean + posts:view_deleted: + type: boolean + read: + type: boolean + purge: + type: boolean + view_thread_tools: + type: boolean + editable: + type: boolean + deletable: + type: boolean + view_deleted: + type: boolean + isAdminOrMod: + type: boolean + disabled: + type: number + tid: + type: string + uid: + type: number + description: A user identifier + topicStaleDays: + type: number + reputation:disabled: + type: number + downvote:disabled: + type: number + feeds:disableRSS: + type: number + bookmarkThreshold: + type: number + necroThreshold: + type: number + postEditDuration: + type: number + postDeleteDuration: + type: number + scrollToMyPost: + type: boolean + allowMultipleBadges: + type: boolean + privateUploads: + type: boolean + rssFeedUrl: + type: string + postIndex: + type: number + loggedInUser: + $ref: ../components/schemas/UserObject.yaml#/UserObject + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/topic/pagination.yaml b/public/openapi/api/topic/pagination.yaml new file mode 100644 index 000000000000..91fc6db29ceb --- /dev/null +++ b/public/openapi/api/topic/pagination.yaml @@ -0,0 +1,19 @@ +get: + tags: + - topics + summary: Get topic pagination data + description: This route retrieves pagination data for a given topic. It is used mainly client-side, as it return data necessary to update a pagination block client-side. + parameters: + - name: topic_id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/Pagination.yaml#/Pagination \ No newline at end of file diff --git a/public/openapi/api/topic/teaser.yaml b/public/openapi/api/topic/teaser.yaml new file mode 100644 index 000000000000..6b0738c1ce85 --- /dev/null +++ b/public/openapi/api/topic/teaser.yaml @@ -0,0 +1,18 @@ +get: + tags: + - topics + summary: Get a topic's teaser post + parameters: + - name: topic_id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "A JSON object containing the teaser post for a topic" + content: + application/json: + schema: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject \ No newline at end of file diff --git a/public/openapi/api/topic/thumb/upload.yaml b/public/openapi/api/topic/thumb/upload.yaml new file mode 100644 index 000000000000..74b096681ec4 --- /dev/null +++ b/public/openapi/api/topic/thumb/upload.yaml @@ -0,0 +1,35 @@ +post: + tags: + - topics + summary: Upload topic thumb + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side + path: + type: string + description: Path to the file in the local file system \ No newline at end of file diff --git a/public/openapi/api/topic/tid.yaml b/public/openapi/api/topic/tid.yaml new file mode 100644 index 000000000000..4c83350b37cf --- /dev/null +++ b/public/openapi/api/topic/tid.yaml @@ -0,0 +1,62 @@ +get: + tags: + - shorthand + summary: Get topic data + parameters: + - name: id + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "A JSON object containing topic data" + content: + application/json: + schema: + type: object + properties: + tid: + type: number + uid: + type: number + cid: + type: number + mainPid: + type: number + teaserPid: + type: number + nullable: true + title: + type: string + slug: + type: string + timestamp: + type: number + lastposttime: + type: number + postcount: + type: number + viewcount: + type: number + deleted: + type: number + locked: + type: number + pinned: + type: number + upvotes: + type: number + downvotes: + type: number + deleterUid: + type: number + titleRaw: + type: string + timestampISO: + type: string + lastposttimeISO: + type: string + votes: + type: number \ No newline at end of file diff --git a/public/openapi/api/uid.yaml b/public/openapi/api/uid.yaml new file mode 100644 index 000000000000..6552e78b9e8a --- /dev/null +++ b/public/openapi/api/uid.yaml @@ -0,0 +1,19 @@ +get: + tags: + - shorthand + summary: Access a user's profile pages + description: >- + This particular shorthand is useful if you are looking to redirect to a user's profile (or other associated pages), but do not know or want to retrieve their userslug, + which is part of the canonical url. + + For example, to go to `uid` 15's list of topics made, you can navigate to `/api/uid/15/topics`, which will send you to the appropriate canonical URL for that user's topics. + parameters: + - name: uid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "Canonical URL of user profile page" \ No newline at end of file diff --git a/public/openapi/api/unread.yaml b/public/openapi/api/unread.yaml new file mode 100644 index 000000000000..f383633cfed6 --- /dev/null +++ b/public/openapi/api/unread.yaml @@ -0,0 +1,290 @@ +get: + tags: + - topics + summary: Get unread topics + description: Returns a list of the current user's unread topics, sorted by the + last post's timestamp. + responses: + "200": + description: An array of unread topic objects sorted by the last post's timestamp. + content: + application/json: + schema: + allOf: + - type: object + properties: + showSelect: + type: boolean + showTopicTools: + type: boolean + nextStart: + type: number + topics: + type: array + items: + type: object + properties: + tid: + type: number + description: A topic identifier + uid: + type: number + description: A user identifier + cid: + type: number + description: A category identifier + mainPid: + type: number + description: The post id of the first post in this topic (also called the + "original post") + title: + type: string + slug: + type: string + timestamp: + type: number + lastposttime: + type: number + postcount: + type: number + viewcount: + type: number + teaserPid: + type: number + upvotes: + type: number + downvotes: + type: number + deleted: + type: number + locked: + type: number + pinned: + type: number + description: Whether or not this particular topic is pinned to the top of the + category + titleRaw: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + lastposttimeISO: + type: string + votes: + type: number + category: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + slug: + type: string + icon: + type: string + image: + nullable: true + imageClass: + nullable: true + type: string + bgColor: + type: string + color: + type: string + disabled: + type: number + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + fullname: + type: string + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + reputation: + type: number + postcount: + type: number + picture: + nullable: true + type: string + signature: + nullable: true + type: string + banned: + type: number + status: + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + banned_until_readable: + type: string + teaser: + type: object + properties: + pid: + type: number + uid: + type: number + description: A user identifier + timestamp: + type: number + tid: + type: number + description: A topic identifier + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + tags: + type: array + items: + type: object + properties: + value: + type: string + valueEscaped: + type: string + color: + type: string + bgColor: + type: string + score: + type: number + isOwner: + type: boolean + ignored: + type: boolean + unread: + type: boolean + bookmark: + nullable: true + unreplied: + type: boolean + icons: + type: array + items: + type: string + index: + type: number + isQuestion: + nullable: true + topicCount: + type: number + title: + type: string + pageCount: + type: number + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCids: + type: array + items: + type: number + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + icon: + type: string + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/unread/total.yaml b/public/openapi/api/unread/total.yaml new file mode 100644 index 000000000000..60a5a1871fe1 --- /dev/null +++ b/public/openapi/api/unread/total.yaml @@ -0,0 +1,11 @@ +get: + tags: + - topics + summary: Get number of unread topics + responses: + "200": + description: "Success" + content: + text/plain: + schema: + type: number \ No newline at end of file diff --git a/public/openapi/api/user.yaml b/public/openapi/api/user.yaml new file mode 100644 index 000000000000..fe202da8a887 --- /dev/null +++ b/public/openapi/api/user.yaml @@ -0,0 +1,86 @@ +get: + tags: + - users + summary: Get user profile + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../components/schemas/PostsObject.yaml#/PostsObject + latestPosts: + $ref: ../components/schemas/PostsObject.yaml#/PostsObject + bestPosts: + $ref: ../components/schemas/PostsObject.yaml#/PostsObject + hasPrivateChat: + type: number + title: + type: string + allowCoverPicture: + type: boolean + selectedGroup: + type: array + items: + type: object + properties: + name: + type: string + slug: + type: string + createtime: + type: number + userTitle: + type: string + description: + type: string + memberCount: + type: number + deleted: + type: string + hidden: + type: number + system: + type: number + private: + type: number + ownerUid: + type: number + icon: + type: string + labelColor: + type: string + cover:url: + type: string + cover:position: + type: string + userTitleEnabled: + type: number + disableJoinRequests: + type: number + disableLeave: + type: number + nameEncoded: + type: string + displayName: + type: string + textColor: + type: string + createtimeISO: + type: string + cover:thumb:url: + type: string + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/best.yaml b/public/openapi/api/user/best.yaml new file mode 100644 index 000000000000..f6e884a37433 --- /dev/null +++ b/public/openapi/api/user/best.yaml @@ -0,0 +1,45 @@ +get: + tags: + - users + summary: Get a user's best performing topics + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/blocks.yaml b/public/openapi/api/user/blocks.yaml new file mode 100644 index 000000000000..e0a16553be1a --- /dev/null +++ b/public/openapi/api/user/blocks.yaml @@ -0,0 +1,30 @@ +get: + tags: + - users + summary: Get user's blocks + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + users: + type: array + items: + $ref: ../../components/schemas/UserObject.yaml#/UserObjectSlim + title: + type: string + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/bookmarks.yaml b/public/openapi/api/user/bookmarks.yaml new file mode 100644 index 000000000000..dead4c2eda4e --- /dev/null +++ b/public/openapi/api/user/bookmarks.yaml @@ -0,0 +1,45 @@ +get: + tags: + - users + summary: Get user's bookmarks + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/categories.yaml b/public/openapi/api/user/categories.yaml new file mode 100644 index 000000000000..57067b4ee7a0 --- /dev/null +++ b/public/openapi/api/user/categories.yaml @@ -0,0 +1,61 @@ +get: + tags: + - users + summary: Get user's watched categories + description: This route retrieves the list of categories and their watch states + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + descriptionParsed: + type: string + depth: + type: number + slug: + type: string + isIgnored: + type: boolean + isWatched: + type: boolean + isNotWatched: + type: boolean + imageClass: + type: string + title: + type: string + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/chats.yaml b/public/openapi/api/user/chats.yaml new file mode 100644 index 000000000000..77b27b7ae867 --- /dev/null +++ b/public/openapi/api/user/chats.yaml @@ -0,0 +1,299 @@ +get: + tags: + - users + summary: Get chat room + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + - name: roomid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + owner: + type: number + roomId: + type: number + roomName: + type: string + messages: + type: array + items: + type: object + properties: + content: + type: string + timestamp: + type: number + fromuid: + type: number + roomId: + type: string + deleted: + type: boolean + system: + type: boolean + edited: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + editedISO: + type: string + messageId: + type: number + fromUser: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + nullable: true + status: + type: string + banned: + type: boolean + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + banned_until_readable: + type: string + deleted: + type: boolean + self: + type: number + newSet: + type: boolean + index: + type: number + cleanedContent: + type: string + isOwner: + type: boolean + isOwner: + type: boolean + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + picture: + type: string + nullable: true + status: + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` + for the user's auto-generated icon + example: "#f44336" + isOwner: + type: boolean + canReply: + type: boolean + groupChat: + type: boolean + usernames: + type: string + maximumUsersInChatRoom: + type: number + maximumChatMessageLength: + type: number + showUserInput: + type: boolean + isAdminOrGlobalMod: + type: boolean + rooms: + type: array + items: + type: object + properties: + owner: + oneOf: + - type: number + - type: string + roomId: + type: number + roomName: + type: string + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + lastonlineISO: + type: string + groupChat: + type: boolean + unread: + type: boolean + teaser: + type: object + properties: + fromuid: + type: number + content: + type: string + timestamp: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + lastonlineISO: + type: string + nullable: true + lastUser: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + lastonline: + type: number + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + lastonlineISO: + type: string + usernames: + type: string + nextStart: + type: number + title: + type: string + uid: + type: number + description: A user identifier + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + canViewInfo: + type: boolean + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/consent.yaml b/public/openapi/api/user/consent.yaml new file mode 100644 index 000000000000..10aff9d2288d --- /dev/null +++ b/public/openapi/api/user/consent.yaml @@ -0,0 +1,34 @@ +get: + tags: + - users + summary: Get user's GDPR consent settings + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + gdpr_consent: + type: boolean + digest: + type: object + properties: + frequency: + type: string + enabled: + type: boolean + title: + type: string + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/downvoted.yaml b/public/openapi/api/user/downvoted.yaml new file mode 100644 index 000000000000..ef2eb8c25b53 --- /dev/null +++ b/public/openapi/api/user/downvoted.yaml @@ -0,0 +1,51 @@ +get: + tags: + - users + summary: Get user's downvoted posts + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject + nextStart: + type: number + noItemsFoundKey: + type: string + description: Translation key for message notifying user that there were no posts found + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + required: + - posts + - nextStart + - noItemsFoundKey + - title + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/edit.yaml b/public/openapi/api/user/edit.yaml new file mode 100644 index 000000000000..8f4c6123f19a --- /dev/null +++ b/public/openapi/api/user/edit.yaml @@ -0,0 +1,66 @@ +get: + tags: + - users + summary: Get user profile for editing + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + maximumSignatureLength: + type: number + maximumAboutMeLength: + type: number + maximumProfileImageSize: + type: number + allowProfilePicture: + type: boolean + allowCoverPicture: + type: boolean + allowProfileImageUploads: + type: number + allowedProfileImageExtensios: + type: string + allowMultipleBadges: + type: boolean + allowAccountDelete: + type: boolean + allowWebsite: + type: boolean + allowAboutMe: + type: boolean + allowSignature: + type: boolean + profileImageDimension: + type: number + defaultAvatar: + type: string + groupSelectSize: + type: number + title: + type: string + editButtons: + type: array + items: + type: object + properties: + link: + type: string + description: A relative path to the page linked to + text: + type: string + description: Button label + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/edit/email.yaml b/public/openapi/api/user/edit/email.yaml new file mode 100644 index 000000000000..91191496ad32 --- /dev/null +++ b/public/openapi/api/user/edit/email.yaml @@ -0,0 +1,27 @@ +get: + tags: + - users + summary: Get configs for email editing + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + hasPassword: + type: boolean + title: + type: string + - $ref: ../../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/edit/password.yaml b/public/openapi/api/user/edit/password.yaml new file mode 100644 index 000000000000..f8eaa0b22d48 --- /dev/null +++ b/public/openapi/api/user/edit/password.yaml @@ -0,0 +1,31 @@ +get: + tags: + - users + summary: Get configs for password editing + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + hasPassword: + type: boolean + minimumPasswordLength: + type: number + minimumPasswordStrength: + type: number + title: + type: string + - $ref: ../../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/edit/username.yaml b/public/openapi/api/user/edit/username.yaml new file mode 100644 index 000000000000..f2213d164544 --- /dev/null +++ b/public/openapi/api/user/edit/username.yaml @@ -0,0 +1,27 @@ +get: + tags: + - users + summary: Get configs for username editing + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + hasPassword: + type: boolean + title: + type: string + - $ref: ../../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/email.yaml b/public/openapi/api/user/email.yaml new file mode 100644 index 000000000000..40713c6b63d6 --- /dev/null +++ b/public/openapi/api/user/email.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Get user by email + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) + parameters: + - name: email + in: path + required: true + schema: + type: string + example: 'test@example.org' + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/UserObject.yaml#/UserObject \ No newline at end of file diff --git a/public/openapi/api/user/followers.yaml b/public/openapi/api/user/followers.yaml new file mode 100644 index 000000000000..a4625c3e9bd7 --- /dev/null +++ b/public/openapi/api/user/followers.yaml @@ -0,0 +1,91 @@ +get: + tags: + - users + summary: Get followers + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + - name: page + in: query + schema: + type: number + example: '' + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + title: + type: string + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + postcount: + type: number + reputation: + type: number + email:confirmed: + type: number + description: Whether the user has confirmed their email address or not + lastonline: + type: number + flags: + nullable: true + banned: + type: number + banned:expire: + type: number + joindate: + type: number + description: A UNIX timestamp representing the moment the user's account was + created + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` + for the user's auto-generated icon + example: "#f44336" + joindateISO: + type: string + lastonlineISO: + type: string + banned_until: + type: number + banned_until_readable: + type: string + administrator: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/following.yaml b/public/openapi/api/user/following.yaml new file mode 100644 index 000000000000..bea518a4f311 --- /dev/null +++ b/public/openapi/api/user/following.yaml @@ -0,0 +1,91 @@ +get: + tags: + - users + summary: Get followed users + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + - name: page + in: query + schema: + type: number + example: '' + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + title: + type: string + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + postcount: + type: number + reputation: + type: number + email:confirmed: + type: number + description: Whether the user has confirmed their email address or not + lastonline: + type: number + flags: + nullable: true + banned: + type: number + banned:expire: + type: number + joindate: + type: number + description: A UNIX timestamp representing the moment the user's account was + created + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` + for the user's auto-generated icon + example: "#f44336" + joindateISO: + type: string + lastonlineISO: + type: string + banned_until: + type: number + banned_until_readable: + type: string + administrator: + type: boolean + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/groups.yaml b/public/openapi/api/user/groups.yaml new file mode 100644 index 000000000000..2e1b3c979359 --- /dev/null +++ b/public/openapi/api/user/groups.yaml @@ -0,0 +1,32 @@ +get: + tags: + - users + summary: Get user's groups + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + title: + type: string + template: + type: object + properties: + name: + type: string + account/groups: + type: boolean + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/ignored.yaml b/public/openapi/api/user/ignored.yaml new file mode 100644 index 000000000000..3fe460885af4 --- /dev/null +++ b/public/openapi/api/user/ignored.yaml @@ -0,0 +1,47 @@ +get: + tags: + - users + summary: Get user's ignored topics + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + topics: + type: array + items: + $ref: ../../components/schemas/TopicObject.yaml#/TopicObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/info.yaml b/public/openapi/api/user/info.yaml new file mode 100644 index 000000000000..da97500a52b4 --- /dev/null +++ b/public/openapi/api/user/info.yaml @@ -0,0 +1,181 @@ +get: + tags: + - users + summary: Get user moderation info + description: Administrators and Global Moderators get access to the `/info` page, which shows some backend data that is useful from a moderation point-of-view (such as IP addresses, recent bans, moderation history, etc). + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + history: + type: object + properties: + flags: + type: array + items: + type: object + properties: + pid: + type: number + timestamp: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + timestampReadable: + type: string + additionalProperties: + description: Contextual data is added to this object (such as topic data, etc.) + bans: + type: array + items: + type: object + properties: + uid: + type: number + timestamp: + type: number + expire: + type: number + fromUid: + type: number + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + until: + type: number + untilReadable: + type: string + timestampReadable: + type: string + timestampISO: + type: string + reason: + type: string + 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 + usernames: + type: array + items: + type: object + properties: + value: + type: string + timestamp: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + emails: + type: array + items: + type: object + properties: + value: + type: string + timestamp: + type: number + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + moderationNotes: + type: array + items: + type: object + properties: + uid: + type: number + note: + type: string + timestamp: + type: number + timestampISO: + type: string + user: + type: object + properties: + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + type: string + uid: + type: number + description: A user identifier + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + title: + type: string + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/posts.yaml b/public/openapi/api/user/posts.yaml new file mode 100644 index 000000000000..9d11ebe920bc --- /dev/null +++ b/public/openapi/api/user/posts.yaml @@ -0,0 +1,45 @@ +get: + tags: + - users + summary: Get a user's posts + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/session.yaml b/public/openapi/api/user/session.yaml new file mode 100644 index 000000000000..e75daf6bb5ea --- /dev/null +++ b/public/openapi/api/user/session.yaml @@ -0,0 +1,20 @@ +delete: + tags: + - users + summary: Revoke a user session + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + - name: uuid + in: path + required: true + schema: + type: string + example: testuuid + responses: + "200": + description: User session revoked \ No newline at end of file diff --git a/public/openapi/api/user/sessions.yaml b/public/openapi/api/user/sessions.yaml new file mode 100644 index 000000000000..8aa719f9ea3c --- /dev/null +++ b/public/openapi/api/user/sessions.yaml @@ -0,0 +1,46 @@ +get: + tags: + - users + summary: Get user's active sessions + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + 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 + title: + type: string + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/settings.yaml b/public/openapi/api/user/settings.yaml new file mode 100644 index 000000000000..e4afbf038078 --- /dev/null +++ b/public/openapi/api/user/settings.yaml @@ -0,0 +1,246 @@ +get: + tags: + - users + summary: Get user's settings + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + settings: + type: object + properties: + showemail: + type: boolean + usePagination: + type: boolean + topicsPerPage: + type: number + postsPerPage: + type: number + topicPostSort: + type: string + openOutgoingLinksInNewTab: + type: boolean + dailyDigestFreq: + type: string + showfullname: + type: boolean + followTopicsOnCreate: + type: boolean + followTopicsOnReply: + type: boolean + restrictChat: + type: boolean + topicSearchEnabled: + type: boolean + categoryTopicSort: + type: string + userLang: + type: string + bootswatchSkin: + type: string + homePageRoute: + type: string + scrollToMyPost: + type: boolean + notificationType_new-chat: + type: string + notificationType_new-reply: + type: string + notificationType_post-edit: + type: string + sendChatNotifications: + nullable: true + sendPostNotifications: + nullable: true + notificationType_upvote: + type: string + notificationType_new-topic: + type: string + notificationType_follow: + type: string + notificationType_group-invite: + type: string + upvoteNotifFreq: + type: string + notificationType_mention: + type: string + acpLang: + type: string + notificationType_new-register: + type: string + notificationType_post-queue: + type: string + notificationType_new-post-flag: + type: string + notificationType_new-user-flag: + type: string + categoryWatchState: + type: string + notificationType_group-request-membership: + type: string + uid: + type: number + description: A user identifier + required: + - showemail + - usePagination + - topicsPerPage + - postsPerPage + - topicPostSort + - openOutgoingLinksInNewTab + - dailyDigestFreq + - showfullname + - followTopicsOnCreate + - followTopicsOnReply + - restrictChat + - topicSearchEnabled + - categoryTopicSort + - userLang + - bootswatchSkin + - homePageRoute + - scrollToMyPost + - notificationType_new-chat + - notificationType_new-reply + - notificationType_upvote + - notificationType_new-topic + - notificationType_follow + - notificationType_group-invite + - upvoteNotifFreq + - acpLang + - notificationType_new-register + - notificationType_post-queue + - notificationType_new-post-flag + - notificationType_new-user-flag + - categoryWatchState + - notificationType_group-request-membership + - uid + languages: + type: array + items: + type: object + properties: + name: + type: string + code: + type: string + dir: + type: string + selected: + type: boolean + acpLanguages: + type: array + items: + type: object + properties: + name: + type: string + code: + type: string + dir: + type: string + selected: + type: boolean + customSettings: + type: array + items: + type: object + properties: {} + additionalProperties: {} + homePageRoutes: + type: array + items: + type: object + properties: + route: + type: string + name: + type: string + selected: + type: boolean + notificationSettings: + type: array + items: + type: object + properties: + name: + type: string + label: + type: string + none: + type: boolean + notification: + type: boolean + email: + type: boolean + notificationemail: + type: boolean + disableEmailSubscriptions: + type: number + dailyDigestFreqOptions: + type: array + items: + type: object + properties: + value: + type: string + name: + type: string + selected: + type: boolean + bootswatchSkinOptions: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + selected: + type: boolean + upvoteNotifFreq: + type: array + items: + type: object + properties: + name: + type: string + selected: + type: boolean + categoryWatchState: + type: object + properties: + watching: + type: boolean + disableCustomUserSkins: + type: number + allowUserHomePage: + type: number + hideFullname: + type: number + hideEmail: + type: number + inTopicSearchAvailable: + type: boolean + maxTopicsPerPage: + type: number + maxPostsPerPage: + type: number + title: + type: string + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/topics.yaml b/public/openapi/api/user/topics.yaml new file mode 100644 index 000000000000..4a6e902970be --- /dev/null +++ b/public/openapi/api/user/topics.yaml @@ -0,0 +1,47 @@ +get: + tags: + - users + summary: Get a user's topics + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + topics: + type: array + items: + $ref: ../../components/schemas/TopicObject.yaml#/TopicObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/uid.yaml b/public/openapi/api/user/uid.yaml new file mode 100644 index 000000000000..7f0ec82b9913 --- /dev/null +++ b/public/openapi/api/user/uid.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Get user by uid + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) + parameters: + - name: uid + in: path + required: true + schema: + type: string + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/UserObject.yaml#/UserObject \ No newline at end of file diff --git a/public/openapi/api/user/uid/export/posts.yaml b/public/openapi/api/user/uid/export/posts.yaml new file mode 100644 index 000000000000..ce2da2309a37 --- /dev/null +++ b/public/openapi/api/user/uid/export/posts.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Export a user's posts (.csv) + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "A CSV file containing a user's posts" + content: + text/csv: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/user/uid/export/profile.yaml b/public/openapi/api/user/uid/export/profile.yaml new file mode 100644 index 000000000000..ffa6b105cc7c --- /dev/null +++ b/public/openapi/api/user/uid/export/profile.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Export a user's profile data (.json) + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "A JSON file containing the user profile" + content: + text/json: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/user/uid/export/uploads.yaml b/public/openapi/api/user/uid/export/uploads.yaml new file mode 100644 index 000000000000..1f29cce6a224 --- /dev/null +++ b/public/openapi/api/user/uid/export/uploads.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Export a user's uploads (.zip) + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: Successful export of user uploads + content: + application/zip: + schema: + type: string + format: binary \ No newline at end of file diff --git a/public/openapi/api/user/uploads.yaml b/public/openapi/api/user/uploads.yaml new file mode 100644 index 000000000000..7d7945eb2875 --- /dev/null +++ b/public/openapi/api/user/uploads.yaml @@ -0,0 +1,37 @@ +get: + tags: + - users + summary: Get user's uploads + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + uploads: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + privateUploads: + type: boolean + title: + type: string + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/upvoted.yaml b/public/openapi/api/user/upvoted.yaml new file mode 100644 index 000000000000..9565b2800061 --- /dev/null +++ b/public/openapi/api/user/upvoted.yaml @@ -0,0 +1,51 @@ +get: + tags: + - users + summary: Get user's upvoted posts + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObjectFull + - type: object + properties: + posts: + $ref: ../../components/schemas/PostsObject.yaml#/PostsObject + nextStart: + type: number + noItemsFoundKey: + type: string + description: Translation key for message notifying user that there were no posts found + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + required: + - posts + - nextStart + - noItemsFoundKey + - title + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/user/username.yaml b/public/openapi/api/user/username.yaml new file mode 100644 index 000000000000..2092c3045147 --- /dev/null +++ b/public/openapi/api/user/username.yaml @@ -0,0 +1,19 @@ +get: + tags: + - users + summary: Get user by username + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) + parameters: + - name: username + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: ../../components/schemas/UserObject.yaml#/UserObject \ No newline at end of file diff --git a/public/openapi/api/user/watched.yaml b/public/openapi/api/user/watched.yaml new file mode 100644 index 000000000000..972c17bc2b6f --- /dev/null +++ b/public/openapi/api/user/watched.yaml @@ -0,0 +1,207 @@ +get: + tags: + - users + summary: Get user's watched topics + parameters: + - name: userslug + in: path + required: true + schema: + type: string + example: admin + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - $ref: ../../components/schemas/UserObject.yaml#/UserObject + - type: object + properties: + aboutmeParsed: + type: string + age: + type: number + emailClass: + type: string + ips: + type: array + items: + type: string + isBlocked: + type: boolean + blocksCount: + type: number + yourid: + type: number + theirid: + type: number + isTargetAdmin: + type: boolean + isAdmin: + type: boolean + isGlobalModerator: + type: boolean + isModerator: + type: boolean + isAdminOrGlobalModerator: + type: boolean + isAdminOrGlobalModeratorOrModerator: + type: boolean + isSelfOrAdminOrGlobalModerator: + type: boolean + canEdit: + type: boolean + canBan: + type: boolean + canChangePassword: + type: boolean + isSelf: + type: boolean + isFollowing: + type: boolean + hasPrivateChat: + type: number + showHidden: + type: boolean + groups: + type: array + items: + type: object + properties: + name: + type: string + slug: + type: string + createtime: + type: number + userTitle: + type: string + description: + type: string + memberCount: + type: number + deleted: + oneOf: + - type: string + - type: number + hidden: + type: number + system: + type: number + private: + type: number + ownerUid: + type: number + icon: + type: string + labelColor: + type: string + userTitleEnabled: + type: number + disableJoinRequests: + type: number + disableLeave: + type: number + nameEncoded: + type: string + displayName: + type: string + textColor: + type: string + createtimeISO: + type: string + cover:thumb:url: + type: string + cover:url: + type: string + cover:position: + type: string + disableSignatures: + type: boolean + reputation:disabled: + type: boolean + downvote:disabled: + type: boolean + profile_links: + type: array + items: + type: object + properties: + id: + type: string + route: + type: string + name: + type: string + visibility: + type: object + properties: + self: + type: boolean + other: + type: boolean + moderator: + type: boolean + globalMod: + type: boolean + admin: + type: boolean + canViewInfo: + type: boolean + public: + type: boolean + icon: + type: string + sso: + type: array + items: + type: object + properties: + associated: + type: boolean + url: + type: string + deauthUrl: + type: string + name: + type: string + icon: + type: string + websiteLink: + type: string + websiteName: + type: string + moderationNote: + type: string + username:disableEdit: + type: boolean + email:disableEdit: + type: boolean + topics: + type: array + items: + $ref: ../../components/schemas/TopicObject.yaml#/TopicObject + nextStart: + type: number + noItemsFoundKey: + type: string + title: + type: string + showSort: + type: boolean + sortOptions: + type: array + items: + type: object + properties: + url: + type: string + name: + type: string + selected: + type: boolean + - $ref: ../../components/schemas/Pagination.yaml#/Pagination + - $ref: ../../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/api/users.yaml b/public/openapi/api/users.yaml new file mode 100644 index 000000000000..a591bd61a587 --- /dev/null +++ b/public/openapi/api/users.yaml @@ -0,0 +1,116 @@ +get: + tags: + - users + summary: Get users + parameters: + - in: query + name: section + schema: + type: string + enum: ['joindate', 'online', 'sort-posts', 'sort-reputation', 'banned', 'flagged'] + required: false + description: Allows filtering of the user list via pre-defined sections + example: 'joindate' + - in: query + name: term + schema: + type: string + required: false + description: Allows for searching of user list + example: '' + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + users: + type: array + items: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + status: + type: string + postcount: + type: number + reputation: + type: number + email:confirmed: + type: number + description: Whether the user has confirmed their email address or not + lastonline: + type: number + flags: + nullable: true + banned: + type: number + banned:expire: + type: number + joindate: + type: number + description: A UNIX timestamp representing the moment the user's account was + created + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without an + avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with `icon:text` + for the user's auto-generated icon + example: "#f44336" + joindateISO: + type: string + lastonlineISO: + type: string + banned_until: + type: number + banned_until_readable: + type: string + userCount: + type: number + title: + type: string + isAdminOrGlobalMod: + type: boolean + isAdmin: + type: boolean + isGlobalMod: + type: boolean + displayUserSearch: + type: boolean + section_joindate: + type: boolean + maximumInvites: + type: number + inviteOnly: + type: boolean + adminInviteOnly: + type: boolean + invites: + type: number + showInviteButton: + type: boolean + reputation:disabled: + type: number + - $ref: ../components/schemas/Pagination.yaml#/Pagination + - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: ../components/schemas/CommonProps.yaml#/CommonProps \ No newline at end of file diff --git a/public/openapi/read.yaml b/public/openapi/read.yaml index 69d9d7a3eb61..9e2ddcb01a2d 100644 --- a/public/openapi/read.yaml +++ b/public/openapi/read.yaml @@ -58,8351 +58,252 @@ tags: description: Convenience and utility routes for accessing other part of the API paths: /api/: - get: - tags: - - home - description: > - This route is used to populate the homepage of NodeBB. It is the main - access point of the forum, and shows a list of categories for navigation - purposes. - summary: Get forum index data - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - title: - type: string - description: The page title - categories: - description: A collection of category data objects - type: array - items: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - children: - type: array - items: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - children: - type: array - items: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - parent: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - posts: - type: array - items: - type: object - properties: - pid: - type: number - timestamp: - type: number - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to - users without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction - with `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - cid: - type: number - description: A category identifier - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - topic: - type: object - properties: - slug: - type: string - title: - type: string - imageClass: - type: string - timesClicked: - type: number - posts: - type: array - items: - type: object - properties: - pid: - type: number - timestamp: - type: number - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - cid: - type: number - description: A category identifier - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - topic: - type: object - properties: - slug: - type: string - title: - type: string - teaser: - type: object - properties: - url: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - pid: - type: number - topic: - type: object - properties: - slug: - type: string - title: - type: string - imageClass: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/index.yaml' /api/admin/dashboard: - get: - tags: - - admin - summary: Get administrative dashboard - responses: - "200": - description: A JSON object containing dashboard data - content: - application/json: - schema: - allOf: - - type: object - properties: - version: - type: string - lookupFailed: - type: boolean - latestVersion: - type: string - nullable: true - upgradeAvailable: - type: boolean - nullable: true - currentPrerelease: - type: boolean - notices: - type: array - items: - type: object - properties: - done: - type: boolean - doneText: - type: string - notDoneText: - type: string - tooltip: - type: string - link: - 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: - nullable: true - type: object - properties: - uid: - type: number - description: A user identifier - ip: - type: string - timestamp: - type: number - user: - $ref: components/schemas/UserObject.yaml#/UserObject - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - showSystemControls: - type: boolean - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/dashboard.yaml' /api/admin/settings/languages: - get: - tags: - - admin - summary: Get language settings - responses: - "200": - description: A JSON object containing available languages and settings - content: - application/json: - schema: - allOf: - - type: object - properties: - languages: - type: array - items: - type: object - properties: - name: - type: string - description: Localised name of the language - code: - type: string - description: A language code (similar to ISO-639) - dir: - type: string - description: Directionality of the language - enum: [ltr, rtl] - selected: - type: boolean - description: Denotes the currently selected default system language on the forum - autoDetectLang: - type: integer - description: Whether the forum will attempt to guess language based on browser's `Accept-Language` header - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/settings/languages.yaml' /api/admin/settings/navigation: - get: - tags: - - admin - summary: Get navigation bar settings - responses: - "200": - description: A JSON object containing navigation settings - content: - application/json: - schema: - allOf: - - type: object - properties: - enabled: - type: array - items: - type: object - properties: - route: - type: string - description: Relative URL to the page the navigation item goes to - title: - type: string - description: Tooltip text - enabled: - type: boolean - iconClass: - type: string - description: A FontAwesome icon string - textClass: - type: string - description: HTML class applied to the text label for this navigation item - text: - type: string - description: Label text for this navigation item - order: - type: integer - description: Ordinality of this item, lower value appears earlier - groups: - type: array - items: - type: object - properties: - displayName: - type: string - selected: - type: boolean - index: - type: integer - description: Seemingly identical to order, but an integer instead of a string - selected: - type: boolean - available: - type: array - items: - type: object - properties: - id: - type: string - description: Unique ID that will be added to the navigation element's `id` property in the DOM - route: - type: string - description: Relative URL to the page the navigation item goes to - title: - type: string - description: Tooltip text - enabled: - type: boolean - iconClass: - type: string - description: A FontAwesome icon string - textClass: - type: string - description: HTML class applied to the text label for this navigation item - text: - type: string - description: Label text for this navigation item - core: - type: boolean - description: Whether the navigation item is provided by core or not (a plugin) - groups: - type: array - items: - type: object - properties: - name: - type: string - displayName: - type: string - properties: - type: object - properties: - targetBlank: - type: boolean - groups: - type: array - items: - type: object - properties: - name: - type: string - displayName: - type: string - navigation: - type: array - description: A clone of `enabled` - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/settings/navigation.yaml' /api/admin/settings/homepage: - get: - tags: - - admin - summary: Get homepage settings - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - routes: - type: array - items: - type: object - properties: - route: - type: string - name: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/settings/homepage.yaml' /api/admin/settings/social: - get: - tags: - - admin - summary: Get post social sharing settings - responses: - "200": - description: "A JSON object containing post social sharing settings" - content: - application/json: - schema: - allOf: - - type: object - properties: - posts: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string - class: - type: string - description: A FontAwesome icon string - activated: - type: boolean - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/settings/social.yaml' /api/admin/manage/categories: - get: - tags: - - admin - summary: Get category management settings - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type : object - properties: - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - disabled: - type: number - icon: - type: string - link: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - backgroundImage: - type: string - nullable: true - imageClass: - type: string - children: - type: array - description: Array of children categories - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/categories.yaml' "/api/admin/manage/categories/{category_id}": - get: - tags: - - admin - summary: Get category settings - parameters: - - name: category_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - category: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - parent: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - icon: - type: string - selected: - type: boolean - level: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - required: - - cid - - name - - icon - selectedCategory: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - selected: - type: boolean - customClasses: - type: array - items: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/categories.yaml' "/api/admin/manage/categories/{category_id}/analytics": - get: - tags: - - admin - summary: Get category anayltics - parameters: - - name: category_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - name: - type: string - analytics: - type: object - properties: - pageviews:hourly: - type: array - items: - type: number - pageviews:daily: - type: array - items: - type: number - topics:daily: - type: array - items: - type: number - posts:daily: - type: array - items: - type: number - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/categories/analytics.yaml' "/api/admin/manage/privileges/{cid}": - get: - tags: - - admin - summary: Get category privileges - parameters: - - name: cid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - privileges: - type: object - properties: - labels: - type: object - properties: - users: - type: array - items: - type: object - properties: - name: - type: string - groups: - type: array - items: - type: object - properties: - name: - type: string - keys: - type: object - properties: - users: - type: array - items: - type: string - groups: - type: array - items: - type: string - users: - type: array - items: - type: object - properties: - name: - type: string - nameEscaped: - type: string - privileges: - type: object - additionalProperties: - type: boolean - description: Each privilege will have a key in this object - groups: - type: array - items: - type: object - properties: - name: - type: string - nameEscaped: - type: string - privileges: - type: object - additionalProperties: - type: boolean - description: Each privilege will have a key in this object - isPrivate: - type: boolean - columnCountUser: - type: number - columnCountUserOther: - type: number - columnCountGroup: - type: number - columnCountGroupOther: - type: number - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - icon: - type: string - selected: - type: boolean - level: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - required: - - cid - - name - - icon - - selected - selectedCategory: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - selected: - type: boolean - cid: - type: number - description: A category identifier - group: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/privileges.yaml' /api/admin/manage/tags: - get: - tags: - - admin - summary: Get tag settings - responses: - "200": - description: "A JSON object containing tag settings" - content: - application/json: - schema: - allOf: - - type: object - properties: - tags: - type: array - items: - type: object - properties: - value: - type: string - description: The tag name - score: - type: number - description: The number of topics containing this tag - valueEscaped: - type: string - color: - type: string - description: Six-character hexadecimal string (with `#` prepended) - example: "#ff0000" - bgColor: - type: string - description: Six-character hexadecimal string (with `#` prepended) - example: "#ff0000" - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/tags.yaml' /api/admin/manage/users: - get: - tags: - - admin - summary: Get users - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - users: - type: array - items: - $ref: components/schemas/UserObject.yaml#/UserObjectACP - page: - type: number - pageCount: - type: number - resultsPerPage: - type: number - latest: - type: boolean - search_display: - type: string - requireEmailConfirmation: - type: number - inviteOnly: - type: boolean - adminInviteOnly: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/users.yaml' /api/admin/manage/users/search: - get: - tags: - - admin - summary: Get users via search term - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - search_display: - type: string - matchCount: - type: number - query: - type: string - uidQuery: - type: string - usernameQuery: - type: string - emailQuery: - type: string - ipQuery: - type: string - pageCount: - type: number - resultsPerPage: - type: number - timing: - type: number - users: - type: array - items: - $ref: components/schemas/UserObject.yaml#/UserObjectACP - - $ref: components/schemas/CommonProps.yaml#/CommonProps - - $ref: components/schemas/Pagination.yaml#/Pagination + $ref: 'api/admin/manage/users/search.yaml' /api/admin/manage/users/latest: - get: - tags: - - admin - summary: Get latest users - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/latest.yaml' /api/admin/manage/users/not-validated: - get: - tags: - - admin - summary: Get non-verified users - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/not-validated.yaml' /api/admin/manage/users/no-posts: - get: - tags: - - admin - summary: Get users with no posts - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/no-posts.yaml' /api/admin/manage/users/top-posters: - get: - tags: - - admin - summary: Get users with the most posts - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/top-posters.yaml' /api/admin/manage/users/most-reputation: - get: - tags: - - admin - summary: Get users with the most reputation - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/most-reputation.yaml' /api/admin/manage/users/inactive: - get: - tags: - - admin - summary: Get inactive users - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/inactive.yaml' /api/admin/manage/users/flagged: - get: - tags: - - admin - summary: Get flagged users - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/flagged.yaml' /api/admin/manage/users/banned: - get: - tags: - - admin - summary: Get banned users - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Replace this responses block with the block from /manage/users/latest" + $ref: 'api/admin/manage/users/banned.yaml' /api/admin/manage/registration: - get: - tags: - - admin - summary: Get registration queue/invites - responses: - "200": - description: "A JSON object containing the registration queue and invites" - content: - application/json: - schema: - allOf: - - type: object - properties: - registrationQueueCount: - type: number - users: - type: array - items: - type: object - properties: - username: - type: string - email: - type: string - ip: - type: string - timestampISO: - type: string - usernameEscaped: - type: string - ipMatch: - type: array - items: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - customActions: - type: array - items: - type: object - properties: - title: - type: string - id: - type: string - class: - type: string - icon: - type: string - customHeaders: - type: array - invites: - type: array - items: - type: object - properties: - uid: - type: number - invitations: - type: array - items: - type: object - properties: - email: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/registration.yaml' /api/admin/manage/admins-mods: - get: - tags: - - admin - summary: Get administrators and moderators - responses: - "200": - description: "A JSON object containing administrators and moderators globally and per-category" - content: - application/json: - schema: - allOf: - - type: object - properties: - admins: - $ref: components/schemas/GroupObject.yaml#/GroupFullObject - globalMods: - $ref: components/schemas/GroupObject.yaml#/GroupFullObject - categories: - type: array - items: - type: object - properties: - cid: - type: number - name: - type: string - level: - type: number - example: 0 - icon: - type: string - description: A FontAwesome icon string - parentCid: - type: number - description: The parent category's identifier - color: - type: string - description: A six-character hexadecimal colour code - bgColor: - type: string - description: A six-character hexadecimal colour code - imageClass: - type: string - depth: - type: number - description: The depth of the category relative to the forum root (`0` is root level) - moderators: - type: array - items: - $ref: components/schemas/UserObject.yaml#/UserObjectSlim - allPrivileges: - type: array - items: - type: string - description: A simple array containing user privilege names (used client-side when giving mod privilege) - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/admins-mods.yaml' /api/admin/manage/groups: - get: - tags: - - admin - summary: Get user groups - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - groups: - type: array - items: - type: object - properties: - name: - type: string - description: - type: string - deleted: - oneOf: - - type: number - - type: string - hidden: - type: number - system: - type: number - userTitle: - type: string - icon: - type: string - labelColor: - type: string - slug: - type: string - createtime: - type: number - memberCount: - type: number - private: - type: number - cover:url: - type: string - cover:position: - type: string - userTitleEnabled: - type: number - disableJoinRequests: - type: number - disableLeave: - type: number - nameEncoded: - type: string - displayName: - type: string - textColor: - type: string - createtimeISO: - type: string - cover:thumb:url: - type: string - ownerUid: - type: number - required: - - name - - description - - hidden - - system - - userTitle - - icon - - labelColor - - slug - - createtime - - memberCount - - private - - cover:url - - cover:position - - userTitleEnabled - - disableJoinRequests - - disableLeave - - nameEncoded - - displayName - - textColor - - createtimeISO - - cover:thumb:url - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - icon: - type: string - selected: - type: boolean - level: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - required: - - cid - - name - - icon - yourid: - type: number - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/groups.yaml' "/api/admin/manage/groups/{name}": - get: - tags: - - admin - summary: Get user group details - parameters: - - name: name - in: path - required: true - schema: - type: string - example: administrators - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - group: - $ref: components/schemas/GroupObject.yaml#/GroupFullObject - groupNames: - type: array - items: - type: object - properties: - encodedName: - type: string - displayName: - type: string - selected: - type: boolean - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - icon: - type: string - selected: - type: boolean - level: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - imageClass: - type: string - required: - - cid - - name - - icon - allowPrivateGroups: - type: number - maximumGroupNameLength: - type: number - maximumGroupTitleLength: - type: number - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/groups.yaml' /api/admin/manage/uploads: - get: - tags: - - admin - summary: Get uploaded files - parameters: - - in: query - name: dir - schema: - type: string - description: Path of the folder, relative to `public/uploads/` - example: / - responses: - "200": - description: "A JSON object containing uploaded files" - content: - application/json: - schema: - allOf: - - type: object - properties: - currentFolder: - type: string - description: Path of the folder, relative to `public/uploads/` - showPids: - type: boolean - description: Whether or not the post identifiers should be shown (this is `true` only for `public/uploads/files/`, as that is where post uploads go) - files: - type: array - items: - type: object - properties: - name: - type: string - path: - type: string - description: Path relative to `currentFolder` - url: - type: string - description: Relative URL ready to be combined with `config.relative_path` on the client-side or templates - fileCount: - type: number - description: For directories, the number of files inside - size: - type: number - description: The size of the file/directory - sizeHumanReadable: - type: string - isDirectory: - type: boolean - isFile: - type: boolean - mtime: - type: number - description: Last modified time of the file, down to the microsecond (expressed as a UNIX timestamp) - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/uploads.yaml' /api/admin/manage/digest: - get: - tags: - - admin - summary: Get system digest info/settings - responses: - "200": - description: "A JSON object containing recent digest sends and settings" - content: - application/json: - schema: - allOf: - - type: object - properties: - title: - type: string - delivery: - type: array - items: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - picture: - nullable: true - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` - for the user's auto-generated icon - example: "#f44336" - lastDelivery: - type: string - setting: - type: boolean - default: - type: string - required: - - title - - delivery - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/manage/digest.yaml' "/api/admin/settings/{term}": - get: - tags: - - admin - summary: Get system settings - parameters: - - name: term - in: path - required: true - schema: - type: string - example: general - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: {} - additionalProperties: - type: object - description: Most of the settings pages have their values loaded on the client-side, so the settings are not exposed server-side. - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/settings.yaml' "/api/admin/appearance/{term}": - get: - tags: - - admin - summary: Get appearance settings - parameters: - - name: term - in: path - required: true - schema: - type: string - example: themes - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/appearance.yaml' /api/admin/extend/plugins: - get: - tags: - - admin - summary: Get system plugin settings - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - installed: - type: array - items: - type: object - properties: - latest: - type: string - description: - type: string - name: - type: string - updated: - type: string - url: - type: string - numInstalls: - type: number - isCompatible: - type: boolean - id: - type: string - installed: - type: boolean - active: - type: boolean - isTheme: - type: boolean - error: - type: boolean - version: - type: string - license: - type: object - properties: - name: - type: string - text: - type: string - nullable: true - outdated: - type: boolean - settingsRoute: - type: string - required: - - latest - - description - - name - - id - - installed - - active - - isTheme - - error - - version - - license - - outdated - installedCount: - type: number - activeCount: - type: number - inactiveCount: - type: number - upgradeCount: - type: number - download: - type: array - items: - type: object - properties: - name: - type: string - updated: - type: string - description: - type: string - latest: - type: string - url: - type: string - numInstalls: - type: number - isCompatible: - type: boolean - id: - type: string - installed: - type: boolean - active: - type: boolean - required: - - name - - updated - - latest - - url - - numInstalls - - isCompatible - - id - - installed - - active - incompatible: - type: array - items: - type: object - properties: - latest: - type: string - description: - type: string - name: - type: string - updated: - type: string - url: - type: string - numInstalls: - type: number - isCompatible: - type: boolean - id: - type: string - installed: - type: boolean - active: - type: boolean - required: - - name - - updated - - latest - - url - - numInstalls - - isCompatible - - id - - installed - - active - trending: - type: array - items: - type: object - properties: - latest: - type: string - description: - type: string - name: - type: string - updated: - type: string - url: - type: string - numInstalls: - type: number - isCompatible: - type: boolean - id: - type: string - installed: - type: boolean - active: - type: boolean - isTheme: - type: boolean - error: - type: boolean - version: - type: string - license: - type: object - properties: - name: - type: string - text: - type: string - nullable: true - outdated: - type: boolean - settingsRoute: - type: string - downloads: - type: number - required: - - latest - - description - - name - - id - - installed - - active - - downloads - submitPluginUsage: - type: number - version: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/extend/plugins.yaml' /api/admin/extend/widgets: - get: - tags: - - admin - summary: Get widget settings - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - templates: - type: array - items: - type: object - properties: - template: - type: string - areas: - type: array - items: - type: object - properties: - name: - type: string - location: - type: string - areas: - type: array - items: - type: object - properties: - name: - type: string - template: - type: string - location: - type: string - data: - type: array - items: - type: object - properties: - widget: - type: string - data: - type: object - properties: - html: - type: string - cid: - type: string - title: - type: string - container: - type: string - groups: - type: array - items: {} - groupsHideFrom: - type: array - items: {} - hide-mobile: - type: string - numTags: - type: string - numUsers: - type: string - text: - type: string - parseAsPost: - type: string - numTopics: - type: string - availableWidgets: - type: array - items: - type: object - properties: - widget: - type: string - name: - type: string - description: - type: string - content: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/extend/widgets.yaml' /api/admin/extend/rewards: - get: - tags: - - admin - summary: Get rewards settings - responses: - "200": - description: "A JSON object containing rewards and their settings" - content: - application/json: - schema: - allOf: - - type: object - properties: - active: - type: array - items: - type: object - properties: - condition: - type: string - conditional: - type: string - value: - type: number - rid: - type: string - claimable: - type: string - id: - type: string - disabled: - type: boolean - rewards: - type: array - items: - additionalProperties: {} - description: Reward-specific properties - conditions: - type: array - items: - type: object - properties: - name: - type: string - condition: - type: string - conditionals: - type: array - items: - type: object - properties: - name: - type: string - conditional: - type: string - rewards: - type: array - items: - type: object - properties: - rid: - type: string - name: - type: string - inputs: - type: array - items: - type: object - properties: - type: - type: string - name: - type: string - label: - type: string - values: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/extend/rewards.yaml' /api/admin/advanced/database: - get: - tags: - - admin - summary: Get database information - responses: - "200": - description: "A JSON object with database status information" - content: - application/json: - schema: - properties: {} - additionalProperties: - type: object - description: Each database configured will have an entry here with information about its runtime status + $ref: 'api/admin/advanced/database.yaml' /api/admin/advanced/events: - get: - tags: - - admin - summary: Get event log - parameters: - - in: query - name: type - schema: - type: string - description: Event name to filter by - example: config-change - - in: query - name: start - schema: - type: string - description: Start date to filter by - example: '' - - in: query - name: end - schema: - type: string - description: End date to filter by - example: '' - - in: query - name: perPage - schema: - type: string - description: Limit the number of events returned per page - example: 20 - responses: - "200": - description: "A JSON object containing " - content: - application/json: - schema: - allOf: - - type: object - properties: - events: - type: array - items: - type: object - properties: - type: - type: string - additionalProperties: - description: Each individual event as added by core/plugins can append their own metadata related to the event - - $ref: components/schemas/Pagination.yaml#/Pagination - - type: object - properties: - types: - type: array - items: - type: object - properties: - value: - type: string - name: - type: string - selected: - type: boolean - query: - additionalProperties: - description: An object containing the query string parameters, if any - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/advanced/events.yaml' /api/admin/advanced/hooks: - get: - tags: - - admin - summary: Get active plugin hooks - responses: - "200": - description: "A JSON object containing all hooks with active listeners" - content: - application/json: - schema: - allOf: - - type: object - properties: - hooks: - type: array - items: - type: object - properties: - hookName: - type: string - description: The name of the hook (also the name used in code) - methods: - type: array - items: - type: object - properties: - id: - type: string - description: Plugin listening to this hook - priority: - type: number - description: Priority level, lower priorities are executed earlier - method: - type: string - description: Stringified method for examination - index: - type: string - description: Internal counter used for DOM element ids - index: - type: string - description: Internal counter used for DOM element ids - count: - type: number - description: The number of listeners subscribed to this hook - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/advanced/hooks.yaml' /api/admin/advanced/logs: - get: - tags: - - admin - summary: Get server-side log output - responses: - "200": - description: "A JSON object containing the server-side log" - content: - application/json: - schema: - allOf: - - type: object - properties: - data: - type: string - description: Output of the server-side log file - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/advanced/logs.yaml' /api/admin/advanced/errors: - get: - tags: - - admin - summary: Get server-side errors - responses: - "200": - description: "A JSON object containing server-side errors" - content: - application/json: - schema: - allOf: - - type: object - properties: - not-found: - type: array - items: - type: object - properties: - value: - type: string - description: Path to the requested URL that returned a 404 - score: - type: number - description: The number of times that URL was requested - analytics: - type: object - properties: - not-found: - type: array - description: 404 responses groups by day, from 6 days ago, to present day - items: - type: number - toobusy: - type: array - description: 503 responses groups by day, from 6 days ago, to present day - items: - type: number - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/advanced/errors.yaml' /api/admin/advanced/errors/export: - get: - tags: - - admin - summary: Export errors (.csv) - responses: - "200": - description: "A CSV file containing server-side errors" - content: - text/csv: - schema: - type: string - format: binary + $ref: 'api/admin/advanced/errors/export.yaml' /api/admin/advanced/cache: - get: - tags: - - admin - summary: Get system cache info - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - postCache: - type: object - properties: - length: - type: number - max: - type: number - nullable: true - itemCount: - type: number - percentFull: - type: number - avgPostSize: - type: number - hits: - type: string - misses: - type: string - hitRatio: - type: string - groupCache: - type: object - properties: - length: - type: number - max: - type: number - itemCount: - type: number - percentFull: - type: number - hits: - type: string - misses: - type: string - hitRatio: - type: string - localCache: - type: object - properties: - length: - type: number - max: - type: number - itemCount: - type: number - percentFull: - type: number - dump: - type: boolean - hits: - type: string - misses: - type: string - hitRatio: - type: string - objectCache: - type: object - properties: - length: - type: number - max: - type: number - itemCount: - type: number - percentFull: - type: number - hits: - type: string - misses: - type: string - hitRatio: - type: string - required: - - postCache - - groupCache - - localCache - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/advanced/cache.yaml' /api/admin/development/logger: - get: - tags: - - admin - summary: Get system logger settings - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/development/logger.yaml' /api/admin/development/info: - get: - tags: - - admin - summary: Get process/system information - responses: - "200": - description: "A JSON object containing process and system information" - content: - application/json: - schema: - allOf: - - type: object - properties: - info: - type: array - items: - type: object - properties: - process: - type: object - properties: - port: - description: An array containing the port numbers configured to be used by NodeBB processes - oneOf: - - type: array - items: - oneOf: - - type: string - - type: number - - type: string - - type: number - pid: - type: number - description: Process id - title: - type: number - description: Executable - version: - type: number - description: NodeBB version - memoryUsage: - type: object - properties: - rss: - type: number - heapTotal: - type: number - heapUsed: - type: number - external: - type: number - arrayBuffers: - type: number - humanReadable: - type: number - required: - - rss - - heapTotal - - heapUsed - - external - - humanReadable - uptime: - type: number - cpuUsage: - type: object - properties: - user: - type: string - system: - type: string - os: - type: object - properties: - hostname: - type: string - type: - type: string - platform: - type: string - arch: - type: string - release: - type: string - load: - type: string - description: CPU load - nodebb: - type: object - properties: - isPrimary: - type: boolean - isCluster: - type: boolean - runJobs: - type: boolean - jobsDisabled: - type: boolean - git: - type: object - properties: - hash: - type: string - hashShort: - type: string - branch: - type: string - stats: - type: object - properties: - onlineGuestCount: - type: number - onlineRegisteredCount: - type: number - socketCount: - type: number - users: - type: object - properties: - categories: - type: number - recent: - type: number - unread: - type: number - topics: - type: number - category: - type: number - topics: - type: array - id: - type: string - infoJSON: - type: string - description: "`info`, but stringified" - host: - type: string - description: Server hostname - port: - description: An array containing the port numbers configured to be used by NodeBB processes - oneOf: - - type: array - items: - oneOf: - - type: string - - type: number - - type: string - - type: number - nodeCount: - type: number - description: The number of NodeBB application processes currently running - timeout: - type: number - ip: - type: string - loggedIn: - type: boolean - relative_path: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/admin/development/info.yaml' /api/admin/users/csv: - get: - tags: - - admin - summary: Get users export (.csv) - parameters: - - in: header - name: referer - schema: - type: string - required: true - example: /admin/manage/users - responses: - "200": - description: "A CSV file containing all registered users" - content: - text/csv: - schema: - type: string - format: binary + $ref: 'api/admin/users/csv.yaml' /api/admin/groups/{groupname}/csv: - get: - tags: - - admin - summary: Get members of a group (.csv) - parameters: - - in: header - name: referer - schema: - type: string - required: true - example: /admin/manage/groups - responses: - "200": - description: "A CSV file containing all users in the group" - content: - text/csv: - schema: - type: string - format: binary + $ref: 'api/admin/groups/csv.yaml' /api/admin/analytics: - get: - tags: - - admin - summary: Get site analytics - parameters: - - 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: "A JSON object containing analytics data" - content: - application/json: - schema: - type: object - properties: - query: - additionalProperties: - description: The query string passed in - result: - type: object - properties: - uniquevisitors: - type: array - items: - type: number - pageviews: - type: array - items: - type: number - pageviews:registered: - type: array - items: - type: number - pageviews:bot: - type: array - items: - type: number - pageviews:guest: - type: array - items: - type: number + $ref: 'api/admin/analytics.yaml' /api/admin/category/uploadpicture: - post: - tags: - - admin - summary: Update category picture (via image upload) - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - cid: - type: number - description: Category identifier whose picture will be set after successful upload - example: 1 - files: - type: array - items: - type: string - format: binary - required: - - cid - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side + $ref: 'api/admin/category/uploadpicture.yaml' /api/admin/uploadfavicon: - post: - tags: - - admin - summary: Upload favicon - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side + $ref: 'api/admin/uploadfavicon.yaml' /api/admin/uploadTouchIcon: - post: - tags: - - admin - summary: Upload Touch Icon - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded logo for the Homescreen/Touch Icon to enable PWA + $ref: 'api/admin/uploadTouchIcon.yaml' /api/admin/uploadMaskableIcon: - post: - tags: - - admin - summary: Upload Maskable Icon - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded logo for the Maskable Icon entry for PWA / A2HS + $ref: 'api/admin/uploadMaskableIcon.yaml' /api/admin/uploadlogo: - post: - tags: - - admin - summary: Upload site logo - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side + $ref: 'api/admin/uploadlogo.yaml' /api/admin/uploadOgImage: - post: - tags: - - admin - summary: Upload site-wide Open Graph Image - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side + $ref: 'api/admin/uploadOgImage.yaml' /api/admin/upload/file: - post: - tags: - - admin - summary: Upload a file - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - folder: - type: string - description: The folder to upload the files to (relative to `public/uploads/`) - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "File uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded file for use client-side + $ref: 'api/admin/upload/file.yaml' /api/admin/uploadDefaultAvatar: - post: - tags: - - admin - summary: Upload default avatar - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side + $ref: 'api/admin/uploadDefaultAvatar.yaml' /api/config: - get: - tags: - - home - summary: Get forum settings - description: This route retrieves forum settings and user-specific settings for client-side options on the forum. - responses: - "200": - description: "" - content: - application/json: - schema: - type: object - properties: - relative_path: - type: string - upload_url: - type: string - assetBaseUrl: - type: string - siteTitle: - type: string - browserTitle: - type: string - titleLayout: - type: string - showSiteTitle: - type: boolean - minimumTitleLength: - type: number - maximumTitleLength: - type: number - minimumPostLength: - type: number - maximumPostLength: - type: number - minimumTagsPerTopic: - type: number - maximumTagsPerTopic: - type: number - minimumTagLength: - type: number - maximumTagLength: - type: number - useOutgoingLinksPage: - type: boolean - allowGuestHandles: - type: boolean - allowTopicsThumbnail: - type: boolean - usePagination: - type: boolean - disableChat: - type: boolean - disableChatMessageEditing: - type: boolean - maximumChatMessageLength: - type: number - socketioTransports: - type: array - items: - type: string - socketioOrigins: - type: string - websocketAddress: - type: string - maxReconnectionAttempts: - type: number - reconnectionDelay: - type: number - topicsPerPage: - type: number - postsPerPage: - type: number - maximumFileSize: - type: number - theme:id: - type: string - theme:src: - type: string - defaultLang: - type: string - userLang: - type: string - loggedIn: - type: boolean - uid: - type: number - description: A user identifier - cache-buster: - type: string - requireEmailConfirmation: - type: boolean - topicPostSort: - type: string - categoryTopicSort: - type: string - csrf_token: - type: string - searchEnabled: - type: boolean - bootswatchSkin: - type: string - enablePostHistory: - type: boolean - timeagoCutoff: - type: number - timeagoCodes: - type: array - items: - type: string - cookies: - type: object - properties: - enabled: - type: boolean - message: - type: string - dismiss: - type: string - link: - type: string - link_url: - type: string - acpLang: - type: string - openOutgoingLinksInNewTab: - type: boolean - topicSearchEnabled: - type: boolean - hideSubCategories: - type: boolean - hideCategoryLastPost: - type: boolean - enableQuickReply: - type: boolean + $ref: 'api/config.yaml' /api/users: - get: - tags: - - users - summary: Get users - parameters: - - in: query - name: section - schema: - type: string - enum: ['joindate', 'online', 'sort-posts', 'sort-reputation', 'banned', 'flagged'] - required: false - description: Allows filtering of the user list via pre-defined sections - example: 'joindate' - - in: query - name: term - schema: - type: string - required: false - description: Allows for searching of user list - example: '' - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - users: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - postcount: - type: number - reputation: - type: number - email:confirmed: - type: number - description: Whether the user has confirmed their email address or not - lastonline: - type: number - flags: - nullable: true - banned: - type: number - banned:expire: - type: number - joindate: - type: number - description: A UNIX timestamp representing the moment the user's account was - created - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` - for the user's auto-generated icon - example: "#f44336" - joindateISO: - type: string - lastonlineISO: - type: string - banned_until: - type: number - banned_until_readable: - type: string - userCount: - type: number - title: - type: string - isAdminOrGlobalMod: - type: boolean - isAdmin: - type: boolean - isGlobalMod: - type: boolean - displayUserSearch: - type: boolean - section_joindate: - type: boolean - maximumInvites: - type: number - inviteOnly: - type: boolean - adminInviteOnly: - type: boolean - invites: - type: number - showInviteButton: - type: boolean - reputation:disabled: - type: number - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/users.yaml' "/api/user/uid/{uid}": - get: - tags: - - users - summary: Get user by uid - description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) - parameters: - - name: uid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/UserObject.yaml#/UserObject + $ref: 'api/user/uid.yaml' "/api/user/username/{username}": - get: - tags: - - users - summary: Get user by username - description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) - parameters: - - name: username - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/UserObject.yaml#/UserObject + $ref: 'api/user/username.yaml' "/api/user/email/{email}": - get: - tags: - - users - summary: Get user by email - description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) - parameters: - - name: email - in: path - required: true - schema: - type: string - example: 'test@example.org' - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/UserObject.yaml#/UserObject + $ref: 'api/user/email.yaml' "/api/user/uid/{userslug}/export/posts": - get: - tags: - - users - summary: Export a user's posts (.csv) - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "A CSV file containing a user's posts" - content: - text/csv: - schema: - type: string - format: binary + $ref: 'api/user/uid/export/posts.yaml' "/api/user/uid/{userslug}/export/uploads": - get: - tags: - - users - summary: Export a user's uploads (.zip) - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: Successful export of user uploads - content: - application/zip: - schema: - type: string - format: binary + $ref: 'api/user/uid/export/uploads.yaml' "/api/user/uid/{userslug}/export/profile": - get: - tags: - - users - summary: Export a user's profile data (.json) - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "A JSON file containing the user profile" - content: - text/json: - schema: - type: string - format: binary + $ref: 'api/user/uid/export/profile.yaml' "/api/post/pid/{id}": - get: - tags: - - shorthand - summary: Get post data - parameters: - - name: id - in: path - required: true - schema: - type: number - example: 1 - responses: - "200": - description: "A JSON object containing post data" - content: - application/json: - schema: - type: object - properties: - uid: - type: number - tid: - type: number - timestamp: - type: number - content: - type: string - pid: - type: number - downvotes: - type: number - upvotes: - type: number - bookmarks: - type: number - deleted: - type: number - deleterUid: - type: number - edited: - type: number - votes: - type: number - timestampISO: - type: string - editedISO: - type: string - upvoted: - type: boolean - downvoted: - type: boolean - flagId: - type: number - description: The flag identifier, if this particular post has been flagged before - replies: - type: number + $ref: 'api/post/pid.yaml' "/api/topic/tid/{id}": - get: - tags: - - shorthand - summary: Get topic data - parameters: - - name: id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "A JSON object containing topic data" - content: - application/json: - schema: - type: object - properties: - tid: - type: number - uid: - type: number - cid: - type: number - mainPid: - type: number - teaserPid: - type: number - nullable: true - title: - type: string - slug: - type: string - timestamp: - type: number - lastposttime: - type: number - postcount: - type: number - viewcount: - type: number - deleted: - type: number - locked: - type: number - pinned: - type: number - upvotes: - type: number - downvotes: - type: number - deleterUid: - type: number - titleRaw: - type: string - timestampISO: - type: string - lastposttimeISO: - type: string - votes: - type: number + $ref: 'api/topic/tid.yaml' "/api/category/cid/{id}": - get: - tags: - - shorthand - summary: Get category data - parameters: - - name: id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "A JSON object containing category data" - content: - application/json: - schema: - type: object - properties: - cid: - type: number - name: - type: number - description: - type: string - descriptionParsed: - type: string - icon: - type: string - bgColor: - type: string - color: - type: string - slug: - type: string - parentCid: - type: number - topic_count: - type: number - post_count: - type: number - disabled: - type: number - order: - type: number - link: - type: string - numRecentReplies: - type: number - class: - type: string - imageClass: - type: string - isSection: - type: number - totalPostCount: - type: number - totalTopicCount: - type: number - minTags: - type: number - maxTags: - type: number + $ref: 'api/category/cid.yaml' /api/categories: - get: - tags: - - categories - summary: Get a list of categories - description: > - This route retrieve the list of categories currently available to the - accessing user. It doesn't necessarily mean that the user can *enter* - the category, as that is a separate privilege. Specifically, this route - will return all categories that grant the calling user the "Find - Category" privilege. - - - Subcategories are also returned, nested under a category's `children` property. - responses: - "200": - description: A list of category objectscurrently available to the accessing user - content: - application/json: - schema: - allOf: - - type: object - properties: - title: - description: The page title - type: string - categories: - description: A collection of category data objects - type: array - items: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - children: - type: array - items: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - children: - type: array - items: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - parent: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - posts: - type: array - items: - type: object - properties: - pid: - type: number - timestamp: - type: number - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to - users without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction - with `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - cid: - type: number - description: A category identifier - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - topic: - type: object - properties: - slug: - type: string - title: - type: string - imageClass: - type: string - timesClicked: - type: number - posts: - type: array - items: - type: object - properties: - pid: - type: number - timestamp: - type: number - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - cid: - type: number - description: A category identifier - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - topic: - type: object - properties: - slug: - type: string - title: - type: string - teaser: - type: object - properties: - url: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - pid: - type: number - topic: - type: object - properties: - slug: - type: string - title: - type: string - imageClass: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/categories.yaml' "/api/categories/{cid}/moderators": - get: - tags: - - categories - summary: Get mods for a category - description: > - This route returns an array of uids that correspond to the moderators - for the category in question. - parameters: - - name: cid - description: The category identifier for the category you wish to look up - in: path - required: true - schema: - type: number - example: 1 - responses: - "200": - description: An array of moderators for the requested category - content: - application/json: - schema: - type: object - properties: - moderators: - type: array - example: - moderators: - - 1 - - 2 - - 3 + $ref: 'api/categories/moderators.yaml' "/api/topic/{topic_id}/{slug}/{post_index}": - get: - tags: - - topics - summary: Get topic data - parameters: - - name: topic_id - in: path - required: true - schema: - type: string - example: 1 - - name: slug - description: This parameter is not required. If omitted, the request will be automatically redirected with the proper topic slug. - in: path - required: true - schema: - type: string - example: test-topic - - name: post_index - description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - tid: - type: number - description: A topic identifier - uid: - type: number - description: A user identifier - cid: - type: number - description: A category identifier - title: - type: string - slug: - type: string - timestamp: - type: number - lastposttime: - type: number - postcount: - type: number - viewcount: - type: number - posterCount: - type: number - description: The number of unique users who made a post in this topic - mainPid: - type: number - description: The post id of the first post in this topic (also called the - "original post") - teaserPid: - type: number - nullable: true - upvotes: - type: number - downvotes: - type: number - deleted: - type: number - locked: - type: number - pinned: - type: number - description: Whether or not this particular topic is pinned to the top of the - category - deleterUid: - type: number - titleRaw: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - lastposttimeISO: - type: string - votes: - type: number - tags: - type: array - items: - type: object - properties: - value: - type: string - valueEscaped: - type: string - color: - type: string - bgColor: - type: string - score: - type: number - posts: - type: array - items: - type: object - properties: - pid: - type: number - uid: - type: number - description: A user identifier - tid: - type: number - description: A topic identifier - content: - type: string - timestamp: - type: number - votes: - type: number - deleted: - type: number - upvotes: - type: number - downvotes: - type: number - bookmarks: - type: number - deleterUid: - type: number - edited: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - editedISO: - type: string - index: - type: number - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - reputation: - type: number - postcount: - type: number - topiccount: - type: number - picture: - type: string - nullable: true - signature: - type: string - banned: - type: number - banned:expire: - type: number - status: - type: string - lastonline: - type: number - groupTitle: - nullable: true - type: string - groupTitleArray: - type: array - items: - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - lastonlineISO: - type: string - banned_until: - type: number - banned_until_readable: - type: string - selectedGroups: - type: array - items: - type: object - properties: - name: - type: string - slug: - type: string - labelColor: - type: string - textColor: - type: string - icon: - type: string - userTitle: - type: string - custom_profile_info: - type: array - items: - type: object - properties: - content: - type: string - description: HTML that is injected into `topic.tpl` of themes that support custom profile info - editor: - nullable: true - bookmarked: - type: boolean - upvoted: - type: boolean - downvoted: - type: boolean - replies: - type: object - properties: - hasMore: - type: boolean - users: - type: array - items: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - administrator: - type: boolean - text: - type: string - count: - type: number - selfPost: - type: boolean - display_edit_tools: - type: boolean - display_delete_tools: - type: boolean - display_moderator_tools: - type: boolean - display_move_tools: - type: boolean - display_post_menu: - type: boolean - flagId: - type: number - description: The flag identifier, if this particular post has been flagged before - category: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - tagWhitelist: - type: array - items: - type: string - minTags: - type: number - maxTags: - type: number - thread_tools: - type: array - items: - type: object - properties: - class: - type: string - title: - type: string - icon: - type: string - isFollowing: - type: boolean - isNotFollowing: - type: boolean - isIgnoring: - type: boolean - bookmark: - nullable: true - postSharing: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string - class: - type: string - activated: - type: boolean - deleter: - nullable: true - merger: - nullable: true - related: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - unreplied: - type: boolean - icons: - type: array - items: - type: string - description: HTML that is rendered by the theme - privileges: - type: object - properties: - topics:reply: - type: boolean - topics:read: - type: boolean - topics:tag: - type: boolean - topics:delete: - type: boolean - posts:edit: - type: boolean - posts:history: - type: boolean - posts:delete: - type: boolean - posts:view_deleted: - type: boolean - read: - type: boolean - purge: - type: boolean - view_thread_tools: - type: boolean - editable: - type: boolean - deletable: - type: boolean - view_deleted: - type: boolean - isAdminOrMod: - type: boolean - disabled: - type: number - tid: - type: string - uid: - type: number - description: A user identifier - topicStaleDays: - type: number - reputation:disabled: - type: number - downvote:disabled: - type: number - feeds:disableRSS: - type: number - bookmarkThreshold: - type: number - necroThreshold: - type: number - postEditDuration: - type: number - postDeleteDuration: - type: number - scrollToMyPost: - type: boolean - allowMultipleBadges: - type: boolean - privateUploads: - type: boolean - rssFeedUrl: - type: string - postIndex: - type: number - loggedInUser: - $ref: components/schemas/UserObject.yaml#/UserObject - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/topic.yaml' /api/recent: - get: - tags: - - topics - summary: Get recent topics - description: Returns a list of topics sorted by timestamp. - responses: - "200": - description: An array of topic objects sorted by timestamp. - content: - application/json: - schema: - allOf: - - type: object - properties: - nextStart: - type: number - topicCount: - type: number - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - tids: - type: array - items: - type: number - canPost: - type: boolean - showSelect: - type: boolean - showTopicTools: - type: boolean - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCategory: - type: object - properties: - icon: - type: string - name: - type: string - bgColor: - type: string - nullable: true - selectedCids: - type: array - items: - type: number - feeds:disableRSS: - type: number - rssFeedUrl: - type: string - title: - type: string - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - terms: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - selectedTerm: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/recent.yaml' "/api/recent/posts/{term}": - get: - tags: - - posts - summary: Get recent posts - parameters: - - name: term - in: path - required: true - schema: - type: string - example: daily - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/PostsObject.yaml#/PostsObject + $ref: 'api/recent/posts.yaml' /api/unread: - get: - tags: - - topics - summary: Get unread topics - description: Returns a list of the current user's unread topics, sorted by the - last post's timestamp. - responses: - "200": - description: An array of unread topic objects sorted by the last post's timestamp. - content: - application/json: - schema: - allOf: - - type: object - properties: - showSelect: - type: boolean - showTopicTools: - type: boolean - nextStart: - type: number - topics: - type: array - items: - type: object - properties: - tid: - type: number - description: A topic identifier - uid: - type: number - description: A user identifier - cid: - type: number - description: A category identifier - mainPid: - type: number - description: The post id of the first post in this topic (also called the - "original post") - title: - type: string - slug: - type: string - timestamp: - type: number - lastposttime: - type: number - postcount: - type: number - viewcount: - type: number - teaserPid: - type: number - upvotes: - type: number - downvotes: - type: number - deleted: - type: number - locked: - type: number - pinned: - type: number - description: Whether or not this particular topic is pinned to the top of the - category - titleRaw: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - lastposttimeISO: - type: string - votes: - type: number - category: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - slug: - type: string - icon: - type: string - image: - nullable: true - imageClass: - nullable: true - type: string - bgColor: - type: string - color: - type: string - disabled: - type: number - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - fullname: - type: string - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - reputation: - type: number - postcount: - type: number - picture: - nullable: true - type: string - signature: - nullable: true - type: string - banned: - type: number - status: - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - banned_until_readable: - type: string - teaser: - type: object - properties: - pid: - type: number - uid: - type: number - description: A user identifier - timestamp: - type: number - tid: - type: number - description: A topic identifier - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - tags: - type: array - items: - type: object - properties: - value: - type: string - valueEscaped: - type: string - color: - type: string - bgColor: - type: string - score: - type: number - isOwner: - type: boolean - ignored: - type: boolean - unread: - type: boolean - bookmark: - nullable: true - unreplied: - type: boolean - icons: - type: array - items: - type: string - index: - type: number - isQuestion: - nullable: true - topicCount: - type: number - title: - type: string - pageCount: - type: number - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCids: - type: array - items: - type: number - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/unread.yaml' /api/unread/total: - get: - tags: - - topics - summary: Get number of unread topics - responses: - "200": - description: "Success" - content: - text/plain: - schema: - type: number + $ref: 'api/unread/total.yaml' "/api/topic/teaser/{topic_id}": - get: - tags: - - topics - summary: Get a topic's teaser post - parameters: - - name: topic_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "A JSON object containing the teaser post for a topic" - content: - application/json: - schema: - $ref: components/schemas/PostsObject.yaml#/PostsObject + $ref: 'api/topic/teaser.yaml' "/api/topic/pagination/{topic_id}": - get: - tags: - - topics - summary: Get topic pagination data - description: This route retrieves pagination data for a given topic. It is used mainly client-side, as it return data necessary to update a pagination block client-side. - parameters: - - name: topic_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/Pagination.yaml#/Pagination + $ref: 'api/topic/pagination.yaml' /api/post/upload: - post: - tags: - - posts - summary: Upload a file to a specific post - description: Provided by NodeBB core and used mainly by the composer, this route allows you to upload an image or file to a post. - responses: - "200": - description: "" - content: - application/json: - schema: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - text/plain: - schema: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - "403": - description: "" - content: - application/json: - schema: - type: string - example: Forbidden - text/plain: - schema: - type: string - example: Forbidden - "500": - description: "" - content: - application/json: - schema: - type: object - properties: - path: - type: string - error: - type: string - text/plain: - schema: - type: object - properties: - path: - type: string - error: - type: string + $ref: 'api/post/upload.yaml' /api/topic/thumb/upload: - post: - tags: - - topics - summary: Upload topic thumb - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side - path: - type: string - description: Path to the file in the local file system + $ref: 'api/topic/thumb/upload.yaml' /api/login: - get: - tags: - - authentication - summary: /api/login - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - loginFormEntry: - type: array - items: - type: object - properties: - label: - type: string - description: A label for the added block - html: - type: string - description: HTML to render on the login page - styleName: - type: string - description: Custom identifier (value is added to `input[id]` and `label[for]`) - alternate_logins: - type: boolean - authentication: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - callbackURL: - type: string - icon: - type: string - scope: - type: string - prompt: - type: string - allowRegistration: - type: boolean - allowLoginWith: - type: string - title: - type: string - allowPasswordReset: - type: boolean - allowLocalLogin: - type: boolean - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/login.yaml' /api/register: - get: - tags: - - authentication - summary: /api/register - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - register_window:spansize: - type: string - alternate_logins: - type: boolean - authentication: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - callbackURL: - type: string - icon: - type: string - scope: - type: string - prompt: - type: string - minimumUsernameLength: - type: number - maximumUsernameLength: - type: number - minimumPasswordLength: - type: number - minimumPasswordStrength: - type: number - regFormEntry: - type: array - items: - type: object - properties: - label: - type: string - html: - type: string - styleName: - type: string - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - # /api/register/complete: - # get: - # tags: - # - authentication - # summary: /api/register/complete - # responses: - # "200": - # description: "" - # content: - # application/json: - # schema: - # allOf: - # - type: object - # properties: - # title: - # type: string - # errors: - # type: array - # items: {} - # sections: - # type: array - # items: - # type: string - # - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/register.yaml' /api/search: - get: - tags: - - search - summary: Get search results - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - matchCount: - type: number - pageCount: - type: number - time: - type: string - multiplePages: - type: boolean - search_query: - type: string - term: - type: string - categories: - type: array - items: - type: object - properties: - value: - oneOf: - - type: string - - type: number - text: - type: string - categoriesCount: - type: number - expandSearch: - type: boolean - showAsPosts: - type: boolean - showAsTopics: - type: boolean - title: - type: string - searchDefaultSortBy: - type: string - privileges: - type: object - properties: - search:users: - type: boolean - search:content: - type: boolean - search:tags: - type: boolean - required: - - posts - - matchCount - - pageCount - - time - - multiplePages - - search_query - - categories - - categoriesCount - - expandSearch - - showAsPosts - - showAsTopics - - title - - searchDefaultSortBy - - permissions - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/search.yaml' "/api/reset": - get: - tags: - - authentication - summary: Get user password reset (step 1) - responses: - "200": - description: "A JSON object containing the 1st step of the user password reset flow" - content: - application/json: - schema: - allOf: - - type: object - properties: - code: - type: string - nullable: true - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/reset.yaml' "/api/reset/{code}": - get: - tags: - - authentication - summary: Get user password reset (step 2) - parameters: - - name: code - in: path - required: true - schema: - type: string - example: testCode - responses: - "200": - description: "A JSON object containing the 2nd step of the user password reset flow" - content: - application/json: - schema: - allOf: - - type: object - properties: - valid: - type: boolean - code: - type: string - minimumPasswordLength: - type: number - minimumPasswordStrength: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/reset.yaml' "/api/email/unsubscribe/{token}": - # TODO: Need GET route here as well - post: - tags: - - emails - summary: Unsubscribe user from email type - parameters: - - name: token - in: path - required: true - schema: - type: string - example: testToken - responses: - "200": - description: "Successfully unsubscribed" - "500": - description: "Server-side error (likely token verification failure)" + $ref: 'api/email/unsubscribe.yaml' "/api/post/{pid}": - get: - tags: - - shorthand - summary: Access a specific post - description: This route comes in handy when all you have is the `pid`, and you want to redirect users to the canonical URL for the topic, with the appropriate topic slug and post index. - parameters: - - name: pid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "Canonical URL of topic" - content: - text/plain: - schema: - type: string + $ref: 'api/post.yaml' /api/flags: - get: - tags: - - flags - summary: Get flags list - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - flags: - type: array - items: - type: object - properties: - state: - type: string - heat: - type: number - description: The number of reports that make up this flag - flagId: - type: number - type: - type: string - targetId: - oneOf: - - type: string - - type: number - targetUid: - type: number - datetime: - type: number - labelClass: - type: string - target_readable: - type: string - datetimeISO: - type: string - assignee: - type: string - nullable: true - analytics: - type: array - items: - type: number - categories: - type: object - properties: {} - additionalProperties: - type: string - description: All categories will be listed here, with the `cid` as the key, and the category name as the value - hasFilter: - type: boolean - filters: - type: object - properties: - page: - type: number - perPage: - type: number - sort: - type: string - title: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/flags.yaml' "/api/flags/{flagId}": - get: - tags: - - flags - summary: /api/flags/{flagId} - parameters: - - name: flagId - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - state: - type: string - flagId: - type: number - type: - type: string - targetId: - type: number - targetUid: - type: number - datetime: - type: number - datetimeISO: - type: string - target_readable: - type: string - target: - type: object - properties: {} - additionalProperties: - description: Properties change depending on the target type (user, post, etc.) - assignee: - type: number - nullable: true - history: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - fields: - type: object - additionalProperties: {} - meta: - type: array - items: - type: object - properties: - key: - type: string - value: - type: string - labelClass: - type: string - enum: ['default', 'primary', 'success', 'info', 'danger'] - required: - - key - datetime: - type: number - datetimeISO: - type: string - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - required: - - uid - - datetime - - datetimeISO - - user - notes: - type: array - items: - type: object - properties: - uid: - type: number - content: - type: string - datetime: - type: number - datetimeISO: - type: string - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - reports: - type: array - items: - type: object - properties: - value: - type: string - timestamp: - type: number - timestampISO: - type: string - reporter: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - reputation: - type: number - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` for - the user's auto-generated icon - example: "#f44336" - type_path: - type: string - assignees: - type: array - items: - $ref: components/schemas/UserObject.yaml#/UserObject - type_bool: - type: object - properties: - post: - type: boolean - user: - type: boolean - empty: - type: boolean - title: - type: string - categories: - type: object - additionalProperties: - type: string - filters: - type: object - properties: - page: - type: number - perPage: - type: number - privileges: - type: object - properties: {} - additionalProperties: - description: "A list of global and admin privileges, and whether the calling user has (or has inherited) them" - type: boolean - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/flags.yaml' /api/post-queue: - get: - tags: - - admin - summary: Get flag data - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - title: - type: string - allCategories: - type: array - items: - type: object - properties: - bgColor: - type: string - cid: - type: number - color: - type: string - disabled: - type: number - disabledClass: - type: boolean - icon: - type: string - imageClass: - type: string - level: - type: string - link: - type: string - name: - type: string - parentCid: - type: number - slug: - type: string - posts: - type: array - items: - allOf: - - type: object - properties: - id: - type: string - uid: - type: number - description: A user identifier - type: - type: string - data: - type: object - properties: - title: - type: string - content: - type: string - thumb: - type: string - cid: - oneOf: - - type: number - - type: string - tags: - type: array - items: {} - uid: - type: number - description: A user identifier - req: - type: object - properties: - uid: - type: number - description: A user identifier - ip: - type: string - host: - type: string - protocol: - type: string - secure: - type: boolean - url: - type: string - path: - type: string - headers: - type: object - properties: - x-real-ip: - type: string - x-forwarded-for: - type: string - x-forwarded-proto: - type: string - host: - type: string - x-nginx-proxy: - type: string - connection: - type: string - accept: - type: string - user-agent: - type: string - sec-fetch-site: - type: string - sec-fetch-mode: - type: string - referer: - type: string - accept-encoding: - type: string - accept-language: - type: string - cookie: - type: string - timestamp: - type: number - fromQueue: - type: boolean - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - rawContent: - type: string - tid: - type: number - description: A topic identifier - toPid: - nullable: true - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - topic: - type: object - properties: - cid: - type: number - title: - type: string - titleRaw: - type: string - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/post-queue.yaml' /api/ip-blacklist: - get: - tags: - - admin - summary: Get IP blacklist settings - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" + $ref: 'api/ip-blacklist.yaml' /api/registration-queue: - get: - tags: - - admin - summary: Get registration queue - responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from corresponding admin route" + $ref: 'api/registration-queue.yaml' /api/tags: - get: - tags: - - tags - summary: Get tags - description: Returns a list of tags sorted by the most topics - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - tags: - type: array - description: An array of tags sorted by the most topics - items: - type: object - properties: - value: - type: string - description: The raw tag - score: - type: number - description: Number of topics tagged by this tag - valueEscaped: - type: string - description: This is the escaped tag value, equal to validator.escape(value) - color: - type: string - bgColor: - type: string - displayTagSearch: - type: boolean - nextStart: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/tags.yaml' "/api/tags/{tag}": - get: - tags: - - tags - summary: Get tag data - description: Returns a list of topics that are tagged with {tag} - parameters: - - name: tag - description: The tag used to retrieve the topics - in: path - required: true - schema: - type: string - example: test - - name: page - description: Page number used in pagination - in: query - required: false - schema: - type: number - example: '' - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - topics: - type: array - description: An array of topics that are all tagged with {tag} - items: - type: object - properties: - tid: - type: number - description: A topic identifier - uid: - type: number - description: A user identifier - cid: - type: number - description: A category identifier - mainPid: - type: number - description: The post id of the first post in this topic (also called the - "original post") - title: - type: string - slug: - type: string - timestamp: - type: number - lastposttime: - type: number - postcount: - type: number - viewcount: - type: number - teaserPid: - oneOf: - - type: number - - type: string - deleted: - type: number - locked: - type: number - pinned: - type: number - description: Whether or not this particular topic is pinned to the top of the - category - upvotes: - type: number - downvotes: - type: number - titleRaw: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - lastposttimeISO: - type: string - votes: - type: number - category: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - slug: - type: string - icon: - type: string - image: - nullable: true - imageClass: - nullable: true - type: string - bgColor: - type: string - color: - type: string - disabled: - type: number - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - reputation: - type: number - postcount: - type: number - picture: - nullable: true - type: string - signature: - nullable: true - type: string - banned: - type: number - status: - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - banned_until_readable: - type: string - fullname: - type: string - teaser: - type: object - properties: - pid: - type: number - uid: - type: number - description: A user identifier - timestamp: - type: number - tid: - type: number - description: A topic identifier - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - tags: - type: array - items: - type: object - properties: - value: - type: string - valueEscaped: - type: string - color: - type: string - bgColor: - type: string - score: - type: number - isOwner: - type: boolean - ignored: - type: boolean - unread: - type: boolean - bookmark: - nullable: true - unreplied: - type: boolean - icons: - type: array - items: {} - index: - type: number - thumb: - type: string - isQuestion: - nullable: true - type: number - isSolved: - type: number - tag: - type: string - title: - type: string - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - rssFeedUrl: - type: string - required: - - topics - - tag - - title - - categories - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/tags.yaml' /api/popular: - get: - tags: - - topics - summary: Get popular topics - description: Returns a list of topics sorted by most replies. In an event of a - tie breaker, the topic with the most views. Can be filtered by All Time, - Day, Week, or Month. - responses: - "200": - description: An array of topic objects sorted by most replies and views. - content: - application/json: - schema: - allOf: - - type: object - properties: - nextStart: - type: number - topicCount: - type: number - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - tids: - type: array - items: - type: number - canPost: - type: boolean - showSelect: - type: boolean - showTopicTools: - type: boolean - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCategory: - type: object - properties: - icon: - type: string - name: - type: string - bgColor: - type: string - nullable: true - selectedCids: - type: array - items: - type: number - feeds:disableRSS: - type: number - rssFeedUrl: - type: string - title: - type: string - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - terms: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - selectedTerm: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/popular.yaml' /api/top: - get: - tags: - - topics - summary: Get top topics - description: Returns a list of topics sorted by most upvotes. - responses: - "200": - description: An array of topic objects sorted by most upvotes. - content: - application/json: - schema: - allOf: - - type: object - properties: - nextStart: - type: number - topicCount: - type: number - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - tids: - type: array - items: - type: number - canPost: - type: boolean - showSelect: - type: boolean - showTopicTools: - type: boolean - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCategory: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - nullable: true - selectedCids: - type: array - items: - type: number - feeds:disableRSS: - type: number - rssFeedUrl: - type: string - title: - type: string - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - icon: - type: string - terms: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - selectedTerm: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/top.yaml' "/api/category/{category_id}/{slug}/{topic_index}": - get: - tags: - - categories - summary: Get a single category - description: This route retrieves a single category's data, along with its children and the topics created inside of the category. - parameters: - - name: category_id - in: path - required: true - schema: - type: string - example: 1 - - name: slug - description: This parameter is not required. If omitted, the request will be automatically redirected with the proper category slug. - in: path - required: true - schema: - type: string - example: test - - name: topic_index - description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - - type: object - properties: - tagWhitelist: - type: array - items: - type: string - unread-class: - type: string - children: - type: array - items: - $ref: components/schemas/CategoryObject.yaml#/CategoryObject - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - nextStart: - type: number - isWatched: - type: boolean - isNotWatched: - type: boolean - isIgnored: - type: boolean - title: - type: string - privileges: - type: object - properties: - topics:create: - type: boolean - topics:read: - type: boolean - topics:tag: - type: boolean - read: - type: boolean - cid: - type: string - uid: - type: number - description: A user identifier - editable: - type: boolean - view_deleted: - type: boolean - isAdminOrMod: - type: boolean - showSelect: - type: boolean - showTopicTools: - type: boolean - topicIndex: - type: number - rssFeedUrl: - type: string - feeds:disableRSS: - type: number - reputation:disabled: - type: number - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/category.yaml' /api/self: - get: - tags: - - shorthand - summary: Access your profile data - description: This shorthand returns the data for the logged in user, identical to the data returned at this route /user/ - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/UserObject.yaml#/UserObjectFull + $ref: 'api/self.yaml' /api/me: - get: - tags: - - shorthand - summary: Access your own profile page - description: >- - This shorthand is useful if you want to link to account profile, but do not want (or have) the `userslug`. It is also especially useful as a - means to instruct users on how to do things, as you can easily redirect them to their own profile pages. - responses: - "200": - description: "Canonical URL to your requested profile page" + $ref: 'api/me.yaml' /api/me/*: - get: - tags: - - shorthand - summary: Access your own profile's sub-pages - description: >- - This shorthand is useful if you want to link to pages in your own account profile, but do not want (or have) the `userslug`. It is also especially useful as a - means to instruct users on how to do things, as you can easily redirect them to their own profile pages. - responses: - "200": - description: "Canonical URL to your requested profile page" + $ref: 'api/me.yaml' "/api/uid/{uid}/*": - get: - tags: - - shorthand - summary: Access a user's profile pages - description: >- - This particular shorthand is useful if you are looking to redirect to a user's profile (or other associated pages), but do not know or want to retrieve their userslug, - which is part of the canonical url. - - For example, to go to `uid` 15's list of topics made, you can navigate to `/api/uid/15/topics`, which will send you to the appropriate canonical URL for that user's topics. - parameters: - - name: uid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "Canonical URL of user profile page" + $ref: 'api/uid.yaml' "/api/user/{userslug}": - get: - tags: - - users - summary: Get user profile - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - latestPosts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - bestPosts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - hasPrivateChat: - type: number - title: - type: string - allowCoverPicture: - type: boolean - selectedGroup: - type: array - items: - type: object - properties: - name: - type: string - slug: - type: string - createtime: - type: number - userTitle: - type: string - description: - type: string - memberCount: - type: number - deleted: - type: string - hidden: - type: number - system: - type: number - private: - type: number - ownerUid: - type: number - icon: - type: string - labelColor: - type: string - cover:url: - type: string - cover:position: - type: string - userTitleEnabled: - type: number - disableJoinRequests: - type: number - disableLeave: - type: number - nameEncoded: - type: string - displayName: - type: string - textColor: - type: string - createtimeISO: - type: string - cover:thumb:url: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user.yaml' "/api/user/{userslug}/following": - get: - tags: - - users - summary: Get followed users - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - - name: page - in: query - schema: - type: number - example: '' - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - title: - type: string - users: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - postcount: - type: number - reputation: - type: number - email:confirmed: - type: number - description: Whether the user has confirmed their email address or not - lastonline: - type: number - flags: - nullable: true - banned: - type: number - banned:expire: - type: number - joindate: - type: number - description: A UNIX timestamp representing the moment the user's account was - created - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` - for the user's auto-generated icon - example: "#f44336" - joindateISO: - type: string - lastonlineISO: - type: string - banned_until: - type: number - banned_until_readable: - type: string - administrator: - type: boolean - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/following.yaml' "/api/user/{userslug}/followers": - get: - tags: - - users - summary: Get followers - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - - name: page - in: query - schema: - type: number - example: '' - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - title: - type: string - users: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - postcount: - type: number - reputation: - type: number - email:confirmed: - type: number - description: Whether the user has confirmed their email address or not - lastonline: - type: number - flags: - nullable: true - banned: - type: number - banned:expire: - type: number - joindate: - type: number - description: A UNIX timestamp representing the moment the user's account was - created - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` - for the user's auto-generated icon - example: "#f44336" - joindateISO: - type: string - lastonlineISO: - type: string - banned_until: - type: number - banned_until_readable: - type: string - administrator: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/followers.yaml' "/api/user/{userslug}/categories": - get: - tags: - - users - summary: Get user's watched categories - description: This route retrieves the list of categories and their watch states - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - descriptionParsed: - type: string - depth: - type: number - slug: - type: string - isIgnored: - type: boolean - isWatched: - type: boolean - isNotWatched: - type: boolean - imageClass: - type: string - title: - type: string - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/categories.yaml' "/api/user/{userslug}/posts": - get: - tags: - - users - summary: Get a user's posts - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/posts.yaml' "/api/user/{userslug}/topics": - get: - tags: - - users - summary: Get a user's topics - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/topics.yaml' "/api/user/{userslug}/best": - get: - tags: - - users - summary: Get a user's best performing topics - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/best.yaml' "/api/user/{userslug}/groups": - get: - tags: - - users - summary: Get user's groups - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - title: - type: string - template: - type: object - properties: - name: - type: string - account/groups: - type: boolean - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/groups.yaml' "/api/user/{userslug}/bookmarks": - get: - tags: - - users - summary: Get user's bookmarks - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/bookmarks.yaml' "/api/user/{userslug}/watched": - get: - tags: - - users - summary: Get user's watched topics - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObject - - type: object - properties: - aboutmeParsed: - type: string - age: - type: number - emailClass: - type: string - ips: - type: array - items: - type: string - isBlocked: - type: boolean - blocksCount: - type: number - yourid: - type: number - theirid: - type: number - isTargetAdmin: - type: boolean - isAdmin: - type: boolean - isGlobalModerator: - type: boolean - isModerator: - type: boolean - isAdminOrGlobalModerator: - type: boolean - isAdminOrGlobalModeratorOrModerator: - type: boolean - isSelfOrAdminOrGlobalModerator: - type: boolean - canEdit: - type: boolean - canBan: - type: boolean - canChangePassword: - type: boolean - isSelf: - type: boolean - isFollowing: - type: boolean - hasPrivateChat: - type: number - showHidden: - type: boolean - groups: - type: array - items: - type: object - properties: - name: - type: string - slug: - type: string - createtime: - type: number - userTitle: - type: string - description: - type: string - memberCount: - type: number - deleted: - oneOf: - - type: string - - type: number - hidden: - type: number - system: - type: number - private: - type: number - ownerUid: - type: number - icon: - type: string - labelColor: - type: string - userTitleEnabled: - type: number - disableJoinRequests: - type: number - disableLeave: - type: number - nameEncoded: - type: string - displayName: - type: string - textColor: - type: string - createtimeISO: - type: string - cover:thumb:url: - type: string - cover:url: - type: string - cover:position: - type: string - disableSignatures: - type: boolean - reputation:disabled: - type: boolean - downvote:disabled: - type: boolean - profile_links: - type: array - items: - type: object - properties: - id: - type: string - route: - type: string - name: - type: string - visibility: - type: object - properties: - self: - type: boolean - other: - type: boolean - moderator: - type: boolean - globalMod: - type: boolean - admin: - type: boolean - canViewInfo: - type: boolean - public: - type: boolean - icon: - type: string - sso: - type: array - items: - type: object - properties: - associated: - type: boolean - url: - type: string - deauthUrl: - type: string - name: - type: string - icon: - type: string - websiteLink: - type: string - websiteName: - type: string - moderationNote: - type: string - username:disableEdit: - type: boolean - email:disableEdit: - type: boolean - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/watched.yaml' "/api/user/{userslug}/ignored": - get: - tags: - - users - summary: Get user's ignored topics - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - nextStart: - type: number - noItemsFoundKey: - type: string - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/ignored.yaml' "/api/user/{userslug}/upvoted": - get: - tags: - - users - summary: Get user's upvoted posts - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - nextStart: - type: number - noItemsFoundKey: - type: string - description: Translation key for message notifying user that there were no posts found - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - required: - - posts - - nextStart - - noItemsFoundKey - - title - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/upvoted.yaml' "/api/user/{userslug}/downvoted": - get: - tags: - - users - summary: Get user's downvoted posts - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - nextStart: - type: number - noItemsFoundKey: - type: string - description: Translation key for message notifying user that there were no posts found - title: - type: string - showSort: - type: boolean - sortOptions: - type: array - items: - type: object - properties: - url: - type: string - name: - type: string - selected: - type: boolean - required: - - posts - - nextStart - - noItemsFoundKey - - title - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/downvoted.yaml' "/api/user/{userslug}/edit": - get: - tags: - - users - summary: Get user profile for editing - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - maximumSignatureLength: - type: number - maximumAboutMeLength: - type: number - maximumProfileImageSize: - type: number - allowProfilePicture: - type: boolean - allowCoverPicture: - type: boolean - allowProfileImageUploads: - type: number - allowedProfileImageExtensios: - type: string - allowMultipleBadges: - type: boolean - allowAccountDelete: - type: boolean - allowWebsite: - type: boolean - allowAboutMe: - type: boolean - allowSignature: - type: boolean - profileImageDimension: - type: number - defaultAvatar: - type: string - groupSelectSize: - type: number - title: - type: string - editButtons: - type: array - items: - type: object - properties: - link: - type: string - description: A relative path to the page linked to - text: - type: string - description: Button label - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/edit.yaml' "/api/user/{userslug}/edit/username": - get: - tags: - - users - summary: Get configs for username editing - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - hasPassword: - type: boolean - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/edit/username.yaml' "/api/user/{userslug}/edit/email": - get: - tags: - - users - summary: Get configs for email editing - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - hasPassword: - type: boolean - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/edit/email.yaml' "/api/user/{userslug}/edit/password": - get: - tags: - - users - summary: Get configs for password editing - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - hasPassword: - type: boolean - minimumPasswordLength: - type: number - minimumPasswordStrength: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/edit/password.yaml' "/api/user/{userslug}/info": - get: - tags: - - users - summary: Get user moderation info - description: Administrators and Global Moderators get access to the `/info` page, which shows some backend data that is useful from a moderation point-of-view (such as IP addresses, recent bans, moderation history, etc). - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - history: - type: object - properties: - flags: - type: array - items: - type: object - properties: - pid: - type: number - timestamp: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - timestampReadable: - type: string - additionalProperties: - description: Contextual data is added to this object (such as topic data, etc.) - bans: - type: array - items: - type: object - properties: - uid: - type: number - timestamp: - type: number - expire: - type: number - fromUid: - type: number - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - until: - type: number - untilReadable: - type: string - timestampReadable: - type: string - timestampISO: - type: string - reason: - type: string - 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 - usernames: - type: array - items: - type: object - properties: - value: - type: string - timestamp: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - emails: - type: array - items: - type: object - properties: - value: - type: string - timestamp: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - moderationNotes: - type: array - items: - type: object - properties: - uid: - type: number - note: - type: string - timestamp: - type: number - timestampISO: - type: string - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - title: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/info.yaml' "/api/user/{userslug}/settings": - get: - tags: - - users - summary: Get user's settings - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - settings: - type: object - properties: - showemail: - type: boolean - usePagination: - type: boolean - topicsPerPage: - type: number - postsPerPage: - type: number - topicPostSort: - type: string - openOutgoingLinksInNewTab: - type: boolean - dailyDigestFreq: - type: string - showfullname: - type: boolean - followTopicsOnCreate: - type: boolean - followTopicsOnReply: - type: boolean - restrictChat: - type: boolean - topicSearchEnabled: - type: boolean - categoryTopicSort: - type: string - userLang: - type: string - bootswatchSkin: - type: string - homePageRoute: - type: string - scrollToMyPost: - type: boolean - notificationType_new-chat: - type: string - notificationType_new-reply: - type: string - notificationType_post-edit: - type: string - sendChatNotifications: - nullable: true - sendPostNotifications: - nullable: true - notificationType_upvote: - type: string - notificationType_new-topic: - type: string - notificationType_follow: - type: string - notificationType_group-invite: - type: string - upvoteNotifFreq: - type: string - notificationType_mention: - type: string - acpLang: - type: string - notificationType_new-register: - type: string - notificationType_post-queue: - type: string - notificationType_new-post-flag: - type: string - notificationType_new-user-flag: - type: string - categoryWatchState: - type: string - notificationType_group-request-membership: - type: string - uid: - type: number - description: A user identifier - required: - - showemail - - usePagination - - topicsPerPage - - postsPerPage - - topicPostSort - - openOutgoingLinksInNewTab - - dailyDigestFreq - - showfullname - - followTopicsOnCreate - - followTopicsOnReply - - restrictChat - - topicSearchEnabled - - categoryTopicSort - - userLang - - bootswatchSkin - - homePageRoute - - scrollToMyPost - - notificationType_new-chat - - notificationType_new-reply - - notificationType_upvote - - notificationType_new-topic - - notificationType_follow - - notificationType_group-invite - - upvoteNotifFreq - - acpLang - - notificationType_new-register - - notificationType_post-queue - - notificationType_new-post-flag - - notificationType_new-user-flag - - categoryWatchState - - notificationType_group-request-membership - - uid - languages: - type: array - items: - type: object - properties: - name: - type: string - code: - type: string - dir: - type: string - selected: - type: boolean - acpLanguages: - type: array - items: - type: object - properties: - name: - type: string - code: - type: string - dir: - type: string - selected: - type: boolean - customSettings: - type: array - items: - type: object - properties: {} - additionalProperties: {} - homePageRoutes: - type: array - items: - type: object - properties: - route: - type: string - name: - type: string - selected: - type: boolean - notificationSettings: - type: array - items: - type: object - properties: - name: - type: string - label: - type: string - none: - type: boolean - notification: - type: boolean - email: - type: boolean - notificationemail: - type: boolean - disableEmailSubscriptions: - type: number - dailyDigestFreqOptions: - type: array - items: - type: object - properties: - value: - type: string - name: - type: string - selected: - type: boolean - bootswatchSkinOptions: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - selected: - type: boolean - upvoteNotifFreq: - type: array - items: - type: object - properties: - name: - type: string - selected: - type: boolean - categoryWatchState: - type: object - properties: - watching: - type: boolean - disableCustomUserSkins: - type: number - allowUserHomePage: - type: number - hideFullname: - type: number - hideEmail: - type: number - inTopicSearchAvailable: - type: boolean - maxTopicsPerPage: - type: number - maxPostsPerPage: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/settings.yaml' "/api/user/{userslug}/uploads": - get: - tags: - - users - summary: Get user's uploads - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - uploads: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - privateUploads: - type: boolean - title: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/uploads.yaml' "/api/user/{userslug}/consent": - get: - tags: - - users - summary: Get user's GDPR consent settings - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - gdpr_consent: - type: boolean - digest: - type: object - properties: - frequency: - type: string - enabled: - type: boolean - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/consent.yaml' "/api/user/{userslug}/blocks": - get: - tags: - - users - summary: Get user's blocks - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - users: - type: array - items: - $ref: components/schemas/UserObject.yaml#/UserObjectSlim - title: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/blocks.yaml' "/api/user/{userslug}/sessions": - get: - tags: - - users - summary: Get user's active sessions - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - $ref: components/schemas/UserObject.yaml#/UserObjectFull - - type: object - properties: - 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 - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/sessions.yaml' "/api/user/{userslug}/session/{uuid}": - delete: - tags: - - users - summary: Revoke a user session - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - - name: uuid - in: path - required: true - schema: - type: string - example: testuuid - responses: - "200": - description: User session revoked + $ref: 'api/user/session.yaml' /api/notifications: - get: - tags: - - notifications - summary: Get notifications - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - notifications: - type: array - items: - type: object - properties: - bodyShort: - type: string - path: - type: string - nid: - type: string - from: - type: number - importance: - type: number - datetime: - type: number - datetimeISO: - type: string - user: - type: object - properties: - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - nullable: true - uid: - type: number - description: A user identifier - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - image: - type: string - nullable: true - read: - type: boolean - readClass: - type: string - filters: - type: array - items: - type: object - additionalProperties: {} - regularFilters: - type: array - items: - type: object - properties: - name: - type: string - filter: - type: string - selected: - type: boolean - required: - - name - - filter - moderatorFilters: - type: array - items: - type: object - properties: - name: - type: string - filter: - type: string - selectedFilter: - type: object - properties: - name: - type: string - filter: - type: string - selected: - type: boolean - title: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/notifications.yaml' "/api/user/{userslug}/chats/{roomid}": - get: - tags: - - users - summary: Get chat room - parameters: - - name: userslug - in: path - required: true - schema: - type: string - example: admin - - name: roomid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - owner: - type: number - roomId: - type: number - roomName: - type: string - messages: - type: array - items: - type: object - properties: - content: - type: string - timestamp: - type: number - fromuid: - type: number - roomId: - type: string - deleted: - type: boolean - system: - type: boolean - edited: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - editedISO: - type: string - messageId: - type: number - fromUser: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - type: string - nullable: true - status: - type: string - banned: - type: boolean - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - banned_until_readable: - type: string - deleted: - type: boolean - self: - type: number - newSet: - type: boolean - index: - type: number - cleanedContent: - type: string - isOwner: - type: boolean - isOwner: - type: boolean - users: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - picture: - type: string - nullable: true - status: - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without an - avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with `icon:text` - for the user's auto-generated icon - example: "#f44336" - isOwner: - type: boolean - canReply: - type: boolean - groupChat: - type: boolean - usernames: - type: string - maximumUsersInChatRoom: - type: number - maximumChatMessageLength: - type: number - showUserInput: - type: boolean - isAdminOrGlobalMod: - type: boolean - rooms: - type: array - items: - type: object - properties: - owner: - oneOf: - - type: number - - type: string - roomId: - type: number - roomName: - type: string - users: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - lastonline: - type: number - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - lastonlineISO: - type: string - groupChat: - type: boolean - unread: - type: boolean - teaser: - type: object - properties: - fromuid: - type: number - content: - type: string - timestamp: - type: number - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - lastonline: - type: number - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - lastonlineISO: - type: string - nullable: true - lastUser: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - status: - type: string - lastonline: - type: number - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - lastonlineISO: - type: string - usernames: - type: string - nextStart: - type: number - title: - type: string - uid: - type: number - description: A user identifier - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - canViewInfo: - type: boolean - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/user/chats.yaml' "/api/chats/{roomid}": - get: - tags: - - shorthand - summary: Access a chat room - description: Redirects a request to the proper chat page URL - parameters: - - name: roomid - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "Chat identifier resolved" - content: - text/plain: - schema: - type: string - description: A relative path to the canonical URL for that chat page + $ref: 'api/chats.yaml' /api/groups: - get: - tags: - - groups - summary: Get user groups - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - groups: - type: array - items: - type: object - properties: - name: - type: string - description: - type: string - deleted: - oneOf: - - type: number - - type: string - hidden: - type: number - system: - type: number - userTitle: - type: string - icon: - type: string - labelColor: - type: string - createtime: - type: number - slug: - type: string - memberCount: - type: number - private: - type: number - userTitleEnabled: - type: number - disableJoinRequests: - type: number - disableLeave: - type: number - nameEncoded: - type: string - displayName: - type: string - textColor: - type: string - createtimeISO: - type: string - cover:thumb:url: - type: string - cover:url: - type: string - cover:position: - type: string - members: - type: array - items: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - picture: - nullable: true - type: string - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - truncated: - type: boolean - ownerUid: - type: number - allowGroupCreation: - type: boolean - nextStart: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/groups.yaml' "/api/groups/{slug}": - get: - tags: - - groups - summary: Get user group details - parameters: - - name: slug - in: path - required: true - schema: - type: string - example: administrators - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - title: - type: string - group: - $ref: components/schemas/GroupObject.yaml#/GroupFullObject - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - isAdmin: - type: boolean - isGlobalMod: - type: boolean - allowPrivateGroups: - type: number - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/groups.yaml' "/api/groups/{slug}/members": - get: - tags: - - groups - summary: Get user group members - parameters: - - name: slug - in: path - required: true - schema: - type: string - example: administrators - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - users: - type: array - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps + $ref: 'api/groups/members.yaml' \ No newline at end of file