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

feat(api): closes #9123 category and topic routes migrated to Write API

Browse Source
This commit is contained in:
Julian Lam
2020-12-29 10:31:53 -05:00
parent 77a5adb616
commit edb8da1ef9
9 changed files with 224 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
public/openapi/components/schemas/CategoryObject.yaml
View File

@@ -1,73 +1,85 @@
CategoryObject:
type: object
properties:
cid:
type: number
description: A category identifier assigned upon category creation (this value cannot be changed)
name:
type: string
description: The category's name/title
description:
type: string
description: A variable-length description of the category (usually displayed underneath the category name)
descriptionParsed:
type: string
description: A variable-length description of the category (usually displayed underneath the category name). Unlike `description`, this value here will have been run through any parsers installed on the forum (e.g. Markdown)
icon:
type: string
description: A FontAwesome icon string
example: fa-comments-o
bgColor:
type: string
description: Theme-related, a six-character hexadecimal string representing the background colour of the category
color:
type: string
description: Theme-related, a six-character hexadecimal string representing the foreground/text colour of the category
slug:
type: string
description: An URL-safe variant of the category title. This value is automatically generated.
readOnly: true
parentCid:
type: number
description: The category identifier for the category that is the immediate ancestor of the current category
topic_count:
type: number
description: The number of topics in the category
post_count:
type: number
description: The number of posts in the category
disabled:
type: number
description: Whether or not this category is disabled.
order:
type: number
description: A number representing the category's place in the hierarchy
link:
type: string
description: If set, attempting to access the forum will go to this external link instead (theme-specific)
numRecentReplies:
type: number
description: The number of posts to render in the API response (this is mostly used at the theme level)
class:
type: string
description: Values that are appended to the `class` attribute of the category's parent/root element
imageClass:
type: string
enum: [auto, cover, contain]
description: The `background-position` of the category background image, if one is set
isSection:
type: number
minTags:
type: number
description: Minimum tags per topic in this category
maxTags:
type: number
description: Maximum tags per topic in this category
postQueue:
type: number
totalPostCount:
type: number
description: The number of posts in the category
totalTopicCount:
type: number
description: The number of topics in the category
allOf:
- type: object
properties:
cid:
type: number
description: A category identifier assigned upon category creation (this value cannot be changed)
name:
type: string
description: The category's name/title
description:
type: string
description: A variable-length description of the category (usually displayed underneath the category name)
descriptionParsed:
type: string
description: A variable-length description of the category (usually displayed underneath the category name). Unlike `description`, this value here will have been run through any parsers installed on the forum (e.g. Markdown)
icon:
type: string
description: A FontAwesome icon string
example: fa-comments-o
bgColor:
type: string
description: Theme-related, a six-character hexadecimal string representing the background colour of the category
color:
type: string
description: Theme-related, a six-character hexadecimal string representing the foreground/text colour of the category
slug:
type: string
description: An URL-safe variant of the category title. This value is automatically generated.
readOnly: true
parentCid:
type: number
description: The category identifier for the category that is the immediate ancestor of the current category
topic_count:
type: number
description: The number of topics in the category
post_count:
type: number
description: The number of posts in the category
disabled:
type: number
description: Whether or not this category is disabled.
order:
type: number
description: A number representing the category's place in the hierarchy
link:
type: string
description: If set, attempting to access the forum will go to this external link instead (theme-specific)
numRecentReplies:
type: number
description: The number of posts to render in the API response (this is mostly used at the theme level)
class:
type: string
description: Values that are appended to the `class` attribute of the category's parent/root element
imageClass:
type: string
enum: [auto, cover, contain]
description: The `background-position` of the category background image, if one is set
isSection:
type: number
minTags:
type: number
description: Minimum tags per topic in this category
maxTags:
type: number
description: Maximum tags per topic in this category
postQueue:
type: number
totalPostCount:
type: number
description: The number of posts in the category
totalTopicCount:
type: number
description: The number of topics in the category
- type: object
description: Optional properties that may or may not be present (except for `cid`, which is always present, and is only here as a hack to pass validation)
properties:
cid:
type: number
description: A category identifier
backgroundImage:
type: string
description: Relative URL to the category's background image
required:
- cid

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

@@ -3,19 +3,8 @@ TopicObject:
- $ref: '#/TopicObjectSlim'
- type: object
properties:
title:
type: string
slug:
type: string
lastposttime:
type: number
teaserPid:
oneOf:
- type: number
- type: string
nullable: true
titleRaw:
type: string
thumbs:
type: array
items:
@@ -218,6 +207,10 @@ TopicObjectSlim:
cid:
type: number
description: A category identifier
title:
type: string
slug:
type: string
mainPid:
type: number
description: The post id of the first post in this topic (also called the "original post")
@@ -231,6 +224,8 @@ TopicObjectSlim:
type: number
deleterUid:
type: number
titleRaw:
type: string
locked:
type: number
pinned:
@@ -258,4 +253,9 @@ TopicObjectSlim:
downvotes:
type: number
votes:
type: number
type: number
teaserPid:
oneOf:
- type: number
- type: string
nullable: true

29
public/openapi/write/categories/cid.yaml
View File

@@ -1,6 +1,31 @@
get:
tags:
- categories
summary: get a category
description: This operation retrieves a category's data
parameters:
- in: path
name: cid
schema:
type: string
required: true
description: a valid category id
example: 2
responses:
'200':
description: Category successfully retrieved
content:
application/json:
schema:
type: object
properties:
status:
$ref: ../../components/schemas/Status.yaml#/Status
response:
$ref: ../../components/schemas/CategoryObject.yaml#/CategoryObject
put:
tags:
- topics
- categories
summary: update a category
description: This operation updates an existing category.
parameters:
@@ -42,7 +67,7 @@ put:
type: string
delete:
tags:
- topics
- categories
summary: delete a category
description: This operation deletes and purges a category and all of its topics and posts (careful, there is no confirmation!)
parameters:

66
public/openapi/write/posts/pid.yaml
View File

@@ -1,3 +1,69 @@
get:
tags:
- posts
summary: get a post
description: This operation retrieves a post's data
parameters:
- in: path
name: pid
schema:
type: string
required: true
description: a valid post id
example: 1
responses:
'200':
description: Post successfully retrieved
content:
application/json:
schema:
type: object
properties:
status:
$ref: ../../components/schemas/Status.yaml#/Status
response:
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
flagId:
type: number
deleted:
type: number
upvotes:
type: number
downvotes:
type: number
deleterUid:
type: number
edited:
type: number
replies:
type: number
bookmarks:
type: number
votes:
type: number
timestampISO:
type: string
description: An ISO 8601 formatted date string (complementing `timestamp`)
editedISO:
type: string
description: An ISO 8601 formatted date string (complementing `timestamp`)
upvoted:
type: boolean
downvoted:
type: boolean
put:
tags:
- posts

25
public/openapi/write/topics/tid.yaml
View File

@@ -1,3 +1,28 @@
get:
tags:
- topics
summary: get a topic
description: This operation retrieves a topic's data
parameters:
- in: path
name: tid
schema:
type: string
required: true
description: a valid topic id
example: 1
responses:
'200':
description: Topic successfully retrieved
content:
application/json:
schema:
type: object
properties:
status:
$ref: ../../components/schemas/Status.yaml#/Status
response:
$ref: ../../components/schemas/TopicObject.yaml#/TopicObjectSlim
post:
tags:
- topics

4
src/controllers/write/categories.js
View File

@@ -15,6 +15,10 @@ const hasAdminPrivilege = async (uid) => {
}
};
Categories.get = async (req, res) => {
helpers.formatApiResponse(200, res, await api.categories.get(req, req.params));
};
Categories.create = async (req, res) => {
await hasAdminPrivilege(req.uid);

4
src/controllers/write/topics.js
View File

@@ -12,6 +12,10 @@ const uploadsController = require('../uploads');
const Topics = module.exports;
Topics.get = async (req, res) => {
helpers.formatApiResponse(200, res, await api.topics.get(req, req.params));
};
Topics.create = async (req, res) => {
const payload = await api.topics.create(req, req.body);
if (payload.queued) {

1
src/routes/write/categories.js
View File

@@ -11,6 +11,7 @@ module.exports = function () {
const middlewares = [middleware.authenticate];
setupApiRoute(router, 'post', '/', [...middlewares, middleware.checkRequired.bind(null, ['name'])], controllers.write.categories.create);
setupApiRoute(router, 'get', '/:cid', [middleware.authenticateOrGuest], controllers.write.categories.get);
setupApiRoute(router, 'put', '/:cid', [...middlewares], controllers.write.categories.update);
setupApiRoute(router, 'delete', '/:cid', [...middlewares], controllers.write.categories.delete);

1
src/routes/write/topics.js
View File

@@ -14,6 +14,7 @@ module.exports = function () {
var multipartMiddleware = multipart();
setupApiRoute(router, 'post', '/', [middleware.authenticateOrGuest, middleware.checkRequired.bind(null, ['cid', 'title', 'content'])], controllers.write.topics.create);
setupApiRoute(router, 'get', '/:tid', [middleware.authenticateOrGuest], controllers.write.topics.get);
setupApiRoute(router, 'post', '/:tid', [middleware.authenticateOrGuest, middleware.checkRequired.bind(null, ['content']), middleware.assert.topic], controllers.write.topics.reply);
setupApiRoute(router, 'delete', '/:tid', [...middlewares], controllers.write.topics.purge);