Skip to content

Node.js based forum software built for the modern web

chore: add OpenAPI schemas for hashtag admin endpoints

Julian Lam5c1608057797
diff --git a/public/openapi/components/schemas/admin/hashtags.yaml b/public/openapi/components/schemas/admin/hashtags.yaml
new file mode 100644
index 0000000000..2dfd1972a8
--- /dev/null
+++ b/public/openapi/components/schemas/admin/hashtags.yaml
@@ -0,0 +1,29 @@
+HashtagObject:
+ type: object
+ properties:
+ tag:
+ type: string
+ description: The hashtag name (without #)
+ example: nodebb
+ relay:
+ type: string
+ description: The relay host
+ example: relay.fedi.buzz
+ actor:
+ type: string
+ description: The actor URL
+ example: https://relay.fedi.buzz/tag/nodebb
+ state:
+ type: string
+ enum: [pending, active, error]
+ description: Follow state
+ example: active
+ createdAt:
+ type: number
+ description: Timestamp when the follow was created
+ example: 1725830000000
+
+HashtagsArray:
+ type: array
+ items:
+ $ref: '#/HashtagObject'
diff --git a/public/openapi/read/admin/federation/hashtags.yaml b/public/openapi/read/admin/federation/hashtags.yaml
new file mode 100644
index 0000000000..6ad3b798b1
--- /dev/null
+++ b/public/openapi/read/admin/federation/hashtags.yaml
@@ -0,0 +1,30 @@
+get:
+ tags:
+ - admin
+ summary: Get federation settings pertaining to hashtags
+ responses:
+ "200":
+ description: ""
+ content:
+ application/json:
+ schema:
+ allOf:
+ - type: object
+ properties:
+ title:
+ type: string
+ hashtags:
+ $ref: ../../../components/schemas/admin/hashtags.yaml#/HashtagsArray
+ relay:
+ type: string
+ description: Current relay host
+ example: relay.fedi.buzz
+ relayOptions:
+ type: array
+ items:
+ type: string
+ description: Available relay options
+ example:
+ - relay.fedi.buzz
+ - tags.pub
+ - $ref: ../../../components/schemas/CommonProps.yaml#/CommonProps
diff --git a/public/openapi/write/admin/activitypub/hashtags.yaml b/public/openapi/write/admin/activitypub/hashtags.yaml
new file mode 100644
index 0000000000..f01d804284
--- /dev/null
+++ b/public/openapi/write/admin/activitypub/hashtags.yaml
@@ -0,0 +1,60 @@
+get:
+ tags:
+ - admin
+ summary: Get followed hashtags
+ description: Returns the list of followed hashtags and relay configuration
+ responses:
+ "200":
+ description: List of followed hashtags
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ status:
+ $ref: ../../../../components/schemas/Status.yaml#/Status
+ response:
+ type: object
+ properties:
+ hashtags:
+ $ref: ../../../../components/schemas/admin/hashtags.yaml#/HashtagsArray
+ relay:
+ type: string
+ description: Current relay host
+ example: relay.fedi.buzz
+post:
+ tags:
+ - admin
+ summary: Follow a hashtag
+ description: Follow a hashtag actor via the configured relay and optionally create an auto-categorization rule
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - tag
+ properties:
+ tag:
+ type: string
+ description: The hashtag name without the # symbol
+ example: nodebb
+ cid:
+ type: number
+ description: Category ID for auto-categorization (optional)
+ example: 1
+ responses:
+ "200":
+ description: Hashtag followed successfully
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ status:
+ $ref: ../../../../components/schemas/Status.yaml#/Status
+ response:
+ $ref: ../../../../components/schemas/admin/hashtags.yaml#/HashtagsArray
+ "400":
+ description: Invalid request data
diff --git a/public/openapi/write/admin/activitypub/hashtags/relay.yaml b/public/openapi/write/admin/activitypub/hashtags/relay.yaml
new file mode 100644
index 0000000000..886a9eba09
--- /dev/null
+++ b/public/openapi/write/admin/activitypub/hashtags/relay.yaml
@@ -0,0 +1,59 @@
+get:
+ tags:
+ - admin
+ summary: Get hashtag relay
+ description: Returns the current relay host for hashtag actors
+ responses:
+ "200":
+ description: Current relay host
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ status:
+ $ref: ../../../../components/schemas/Status.yaml#/Status
+ response:
+ type: object
+ properties:
+ relay:
+ type: string
+ description: Current relay host
+ example: relay.fedi.buzz
+put:
+ tags:
+ - admin
+ summary: Set hashtag relay
+ description: Set the relay host for hashtag actors; triggers migration of existing follows if changed
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - host
+ properties:
+ host:
+ type: string
+ description: The relay host
+ example: relay.fedi.buzz
+ responses:
+ "200":
+ description: Relay host updated
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ status:
+ $ref: ../../../../components/schemas/Status.yaml#/Status
+ response:
+ type: object
+ properties:
+ relay:
+ type: string
+ description: Updated relay host
+ example: relay.fedi.buzz
+ "400":
+ description: Invalid relay host
diff --git a/public/openapi/write/admin/activitypub/hashtags/tag.yaml b/public/openapi/write/admin/activitypub/hashtags/tag.yaml
new file mode 100644
index 0000000000..e76e818d03
--- /dev/null
+++ b/public/openapi/write/admin/activitypub/hashtags/tag.yaml
@@ -0,0 +1,24 @@
+delete:
+ tags:
+ - admin
+ summary: Unfollow a hashtag
+ description: Remove a followed hashtag and its auto-categorization rule
+ parameters:
+ - in: path
+ name: tag
+ schema:
+ type: string
+ required: true
+ example: nodebb
+ responses:
+ "200":
+ description: Hashtag unfollowed successfully
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ status:
+ $ref: ../../../../components/schemas/Status.yaml#/Status
+ response:
+ $ref: ../../../../components/schemas/admin/hashtags.yaml#/HashtagsArray