diff --git a/public/openapi/components/schemas/CategoryObject.yaml b/public/openapi/components/schemas/CategoryObject.yaml index bbeca1cf9f..384349bc9e 100644 --- a/public/openapi/components/schemas/CategoryObject.yaml +++ b/public/openapi/components/schemas/CategoryObject.yaml @@ -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 \ No newline at end of file + 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 \ No newline at end of file diff --git a/public/openapi/components/schemas/TopicObject.yaml b/public/openapi/components/schemas/TopicObject.yaml index 653c0d3c53..9c95a4a5ed 100644 --- a/public/openapi/components/schemas/TopicObject.yaml +++ b/public/openapi/components/schemas/TopicObject.yaml @@ -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 \ No newline at end of file + type: number + teaserPid: + oneOf: + - type: number + - type: string + nullable: true \ No newline at end of file diff --git a/public/openapi/write/categories/cid.yaml b/public/openapi/write/categories/cid.yaml index af7790088c..bcb50225a5 100644 --- a/public/openapi/write/categories/cid.yaml +++ b/public/openapi/write/categories/cid.yaml @@ -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: diff --git a/public/openapi/write/posts/pid.yaml b/public/openapi/write/posts/pid.yaml index 2d439bd8f0..593a7acd01 100644 --- a/public/openapi/write/posts/pid.yaml +++ b/public/openapi/write/posts/pid.yaml @@ -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 diff --git a/public/openapi/write/topics/tid.yaml b/public/openapi/write/topics/tid.yaml index 04a5e98aee..8e68efe25a 100644 --- a/public/openapi/write/topics/tid.yaml +++ b/public/openapi/write/topics/tid.yaml @@ -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 diff --git a/src/controllers/write/categories.js b/src/controllers/write/categories.js index d9bbd8ece6..17f56ab78b 100644 --- a/src/controllers/write/categories.js +++ b/src/controllers/write/categories.js @@ -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); diff --git a/src/controllers/write/topics.js b/src/controllers/write/topics.js index c91654530b..c20cc6a269 100644 --- a/src/controllers/write/topics.js +++ b/src/controllers/write/topics.js @@ -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) { diff --git a/src/routes/write/categories.js b/src/routes/write/categories.js index beb73b90b8..a87456a657 100644 --- a/src/routes/write/categories.js +++ b/src/routes/write/categories.js @@ -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); diff --git a/src/routes/write/topics.js b/src/routes/write/topics.js index 9203146588..d2c05a38bd 100644 --- a/src/routes/write/topics.js +++ b/src/routes/write/topics.js @@ -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);