oapi: root level routes

assets/openapi.json

@@ -3380,6 +3380,29 @@
                     "welcome_channels"
                 ]
             },
+            "Categories": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "integer"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "localizations": {
+                        "type": "string"
+                    },
+                    "is_primary": {
+                        "type": "boolean"
+                    }
+                },
+                "required": [
+                    "id",
+                    "is_primary",
+                    "localizations",
+                    "name"
+                ]
+            },
             "GuildMessagesSearchMessage": {
                 "type": "object",
                 "properties": {
@@ -5886,6 +5909,38 @@
                     "$ref": "#/components/schemas/Webhook"
                 }
             },
+            "DiscoverableGuildsResponse": {
+                "type": "object",
+                "properties": {
+                    "total": {
+                        "type": "integer"
+                    },
+                    "guilds": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/Guild"
+                        }
+                    },
+                    "offset": {
+                        "type": "integer"
+                    },
+                    "limit": {
+                        "type": "integer"
+                    }
+                },
+                "required": [
+                    "guilds",
+                    "limit",
+                    "offset",
+                    "total"
+                ]
+            },
+            "DiscoveryCategoriesResponse": {
+                "type": "array",
+                "items": {
+                    "$ref": "#/components/schemas/Categories"
+                }
+            },
             "GatewayBotResponse": {
                 "type": "object",
                 "properties": {
@@ -6211,6 +6266,24 @@
                     "purged"
                 ]
             },
+            "GuildRecommendationsResponse": {
+                "type": "object",
+                "properties": {
+                    "recommended_guilds": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/Guild"
+                        }
+                    },
+                    "load_id": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "load_id",
+                    "recommended_guilds"
+                ]
+            },
             "GuildResponse": {
                 "type": "object",
                 "properties": {
@@ -6404,6 +6477,79 @@
                     "gateway"
                 ]
             },
+            "InstancePingResponse": {
+                "type": "object",
+                "properties": {
+                    "ping": {
+                        "type": "string",
+                        "enum": [
+                            "pong!"
+                        ]
+                    },
+                    "instance": {
+                        "type": "object",
+                        "properties": {
+                            "id": {
+                                "type": "string"
+                            },
+                            "name": {
+                                "type": "string"
+                            },
+                            "description": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            },
+                            "image": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            },
+                            "correspondenceEmail": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            },
+                            "correspondenceUserID": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            },
+                            "frontPage": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            },
+                            "tosPage": {
+                                "type": [
+                                    "null",
+                                    "string"
+                                ]
+                            }
+                        },
+                        "additionalProperties": false,
+                        "required": [
+                            "correspondenceEmail",
+                            "correspondenceUserID",
+                            "description",
+                            "frontPage",
+                            "id",
+                            "image",
+                            "name",
+                            "tosPage"
+                        ]
+                    }
+                },
+                "required": [
+                    "instance",
+                    "ping"
+                ]
+            },
             "InstanceStatsResponse": {
                 "type": "object",
                 "properties": {
@@ -6655,6 +6801,30 @@
                     "token"
                 ]
             },
+            "UpdatesResponse": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string"
+                    },
+                    "pub_date": {
+                        "type": "string"
+                    },
+                    "url": {
+                        "type": "string"
+                    },
+                    "notes": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                },
+                "required": [
+                    "name",
+                    "notes",
+                    "pub_date",
+                    "url"
+                ]
+            },
             "UserNoteResponse": {
                 "type": "object",
                 "properties": {
@@ -8436,8 +8606,35 @@
         "/updates/": {
             "get": {
                 "responses": {
-                    "default": {
+                    "200": {
-                        "description": "No description available"
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/UpdatesResponse"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/APIErrorResponse"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/APIErrorResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -8595,8 +8792,18 @@
                     }
                 ],
                 "responses": {
-                    "default": {
+                    "200": {
                         "description": "No description available"
+                    },
+                    "403": {
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/APIErrorResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -8683,7 +8890,7 @@
         "/science/": {
             "post": {
                 "responses": {
-                    "default": {
+                    "204": {
                         "description": "No description available"
                     }
                 },
@@ -8840,8 +9047,15 @@
         "/ping/": {
             "get": {
                 "responses": {
-                    "default": {
+                    "200": {
-                        "description": "No description available"
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/InstancePingResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -11204,8 +11418,15 @@
                     }
                 ],
                 "responses": {
-                    "default": {
+                    "200": {
-                        "description": "No description available"
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/GuildRecommendationsResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -11393,8 +11614,18 @@
         "/download/": {
             "get": {
                 "responses": {
-                    "default": {
+                    "302": {
                         "description": "No description available"
+                    },
+                    "404": {
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/APIErrorResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -11410,8 +11641,15 @@
                     }
                 ],
                 "responses": {
-                    "default": {
+                    "200": {
-                        "description": "No description available"
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/DiscoveryCategoriesResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [
@@ -11427,8 +11665,15 @@
                     }
                 ],
                 "responses": {
-                    "default": {
+                    "200": {
-                        "description": "No description available"
+                        "description": "",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/DiscoverableGuildsResponse"
+                                }
+                            }
+                        }
                     }
                 },
                 "tags": [

src/api/routes/discoverable-guilds.ts

@@ -16,22 +16,33 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Guild, Config } from "@spacebar/util";
+import { Config, Guild } from "@spacebar/util";
 
-import { Router, Request, Response } from "express";
 import { route } from "@spacebar/api";
+import { Request, Response, Router } from "express";
 import { Like } from "typeorm";
 
 const router = Router();
 
-router.get("/", route({}), async (req: Request, res: Response) => {
+router.get(
+	"/",
+	route({
+		responses: {
+			200: {
+				body: "DiscoverableGuildsResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
 		const { offset, limit, categories } = req.query;
 		const showAllGuilds = Config.get().guild.discovery.showAllGuilds;
 		const configLimit = Config.get().guild.discovery.limit;
 		let guilds;
 		if (categories == undefined) {
 			guilds = showAllGuilds
-			? await Guild.find({ take: Math.abs(Number(limit || configLimit)) })
+				? await Guild.find({
+						take: Math.abs(Number(limit || configLimit)),
+				  })
 				: await Guild.find({
 						where: { features: Like(`%DISCOVERABLE%`) },
 						take: Math.abs(Number(limit || configLimit)),
@@ -59,6 +70,7 @@ router.get("/", route({}), async (req: Request, res: Response) => {
 			offset: Number(offset || Config.get().guild.discovery.offset),
 			limit: Number(limit || configLimit),
 		});
-});
+	},
+);
 
 export default router;

src/api/routes/discovery.ts

@@ -16,13 +16,22 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Categories } from "@spacebar/util";
-import { Router, Response, Request } from "express";
 import { route } from "@spacebar/api";
+import { Categories } from "@spacebar/util";
+import { Request, Response, Router } from "express";
 
 const router = Router();
 
-router.get("/categories", route({}), async (req: Request, res: Response) => {
+router.get(
+	"/categories",
+	route({
+		responses: {
+			200: {
+				body: "DiscoveryCategoriesResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
 		// TODO:
 		// Get locale instead
 
@@ -34,6 +43,7 @@ router.get("/categories", route({}), async (req: Request, res: Response) => {
 			: await Categories.find({ where: { is_primary: true } });
 
 		res.send(out);
-});
+	},
+);
 
 export default router;

src/api/routes/download.ts

@@ -16,13 +16,23 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Router, Response, Request } from "express";
 import { route } from "@spacebar/api";
 import { FieldErrors, Release } from "@spacebar/util";
+import { Request, Response, Router } from "express";
 
 const router = Router();
 
-router.get("/", route({}), async (req: Request, res: Response) => {
+router.get(
+	"/",
+	route({
+		responses: {
+			302: {},
+			404: {
+				body: "APIErrorResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
 		const { platform } = req.query;
 
 		if (!platform)
@@ -42,6 +52,7 @@ router.get("/", route({}), async (req: Request, res: Response) => {
 		});
 
 		res.redirect(release.url);
-});
+	},
+);
 
 export default router;

src/api/routes/guild-recommendations.ts

@@ -16,15 +16,24 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Guild, Config } from "@spacebar/util";
+import { Config, Guild } from "@spacebar/util";
 
-import { Router, Request, Response } from "express";
 import { route } from "@spacebar/api";
+import { Request, Response, Router } from "express";
 import { Like } from "typeorm";
 
 const router = Router();
 
-router.get("/", route({}), async (req: Request, res: Response) => {
+router.get(
+	"/",
+	route({
+		responses: {
+			200: {
+				body: "GuildRecommendationsResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
 		// const { limit, personalization_disabled } = req.query;
 		const { limit } = req.query;
 		const showAllGuilds = Config.get().guild.discovery.showAllGuilds;
@@ -44,6 +53,7 @@ router.get("/", route({}), async (req: Request, res: Response) => {
 			recommended_guilds: guilds,
 			load_id: `server_recs/${genLoadId(32)}`,
 		}).status(200);
-});
+	},
+);
 
 export default router;

src/api/routes/ping.ts

@@ -16,13 +16,22 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Router, Response, Request } from "express";
 import { route } from "@spacebar/api";
 import { Config } from "@spacebar/util";
+import { Request, Response, Router } from "express";
 
 const router = Router();
 
-router.get("/", route({}), (req: Request, res: Response) => {
+router.get(
+	"/",
+	route({
+		responses: {
+			200: {
+				body: "InstancePingResponse",
+			},
+		},
+	}),
+	(req: Request, res: Response) => {
 		const { general } = Config.get();
 		res.send({
 			ping: "pong!",
@@ -39,6 +48,7 @@ router.get("/", route({}), (req: Request, res: Response) => {
 				tosPage: general.tosPage,
 			},
 		});
-});
+	},
+);
 
 export default router;

src/api/routes/science.ts

@@ -16,14 +16,22 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Router, Response, Request } from "express";
 import { route } from "@spacebar/api";
+import { Request, Response, Router } from "express";
 
 const router = Router();
 
-router.post("/", route({}), (req: Request, res: Response) => {
+router.post(
+	"/",
+	route({
+		responses: {
+			204: {},
+		},
+	}),
+	(req: Request, res: Response) => {
 		// TODO:
 		res.sendStatus(204);
-});
+	},
+);
 
 export default router;

src/api/routes/stop.ts

@@ -16,14 +16,22 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Router, Request, Response } from "express";
 import { route } from "@spacebar/api";
+import { Request, Response, Router } from "express";
 
 const router: Router = Router();
 
 router.post(
 	"/",
-	route({ right: "OPERATOR" }),
+	route({
+		right: "OPERATOR",
+		responses: {
+			200: {},
+			403: {
+				body: "APIErrorResponse",
+			},
+		},
+	}),
 	async (req: Request, res: Response) => {
 		console.log(`/stop was called by ${req.user_id} at ${new Date()}`);
 		res.sendStatus(200);

src/api/routes/updates.ts

@@ -16,13 +16,28 @@
 	along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-import { Router, Response, Request } from "express";
 import { route } from "@spacebar/api";
 import { FieldErrors, Release } from "@spacebar/util";
+import { Request, Response, Router } from "express";
 
 const router = Router();
 
-router.get("/", route({}), async (req: Request, res: Response) => {
+router.get(
+	"/",
+	route({
+		responses: {
+			200: {
+				body: "UpdatesResponse",
+			},
+			400: {
+				body: "APIErrorResponse",
+			},
+			404: {
+				body: "APIErrorResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
 		const platform = req.query.platform;
 
 		if (!platform)
@@ -47,6 +62,7 @@ router.get("/", route({}), async (req: Request, res: Response) => {
 			url: release.url,
 			notes: release.notes,
 		});
-});
+	},
+);
 
 export default router;

src/util/schemas/responses/DiscoverableGuildsResponse.ts

@@ -0,0 +1,8 @@
+import { Guild } from "../../entities";
+
+export interface DiscoverableGuildsResponse {
+	total: number;
+	guilds: Guild[];
+	offset: number;
+	limit: number;
+}

src/util/schemas/responses/DiscoveryCategoriesResponse.ts

@@ -0,0 +1,3 @@
+import { Categories } from "../../entities";
+
+export type DiscoveryCategoriesResponse = Categories[];

src/util/schemas/responses/GuildRecommendationsResponse.ts

@@ -0,0 +1,6 @@
+import { Guild } from "../../entities";
+
+export interface GuildRecommendationsResponse {
+	recommended_guilds: Guild[];
+	load_id: string;
+}

src/util/schemas/responses/InstancePingResponse.ts

@@ -0,0 +1,13 @@
+export interface InstancePingResponse {
+	ping: "pong!";
+	instance: {
+		id: string;
+		name: string;
+		description: string | null;
+		image: string | null;
+		correspondenceEmail: string | null;
+		correspondenceUserID: string | null;
+		frontPage: string | null;
+		tosPage: string | null;
+	};
+}

src/util/schemas/responses/UpdatesResponse.ts

@@ -0,0 +1,6 @@
+export interface UpdatesResponse {
+	name: string;
+	pub_date: string;
+	url: string;
+	notes: string | null;
+}

src/util/schemas/responses/index.ts

@@ -9,6 +9,8 @@ export * from "./CaptchaRequiredResponse";
 export * from "./ChannelInvitesResponse";
 export * from "./ChannelPinsResponse";
 export * from "./ChannelWebhooksResponse";
+export * from "./DiscoverableGuildsResponse";
+export * from "./DiscoveryCategoriesResponse";
 export * from "./GatewayBotResponse";
 export * from "./GatewayResponse";
 export * from "./GeneralConfigurationResponse";
@@ -22,6 +24,7 @@ export * from "./GuildInvitesResponse";
 export * from "./GuildMembersResponse";
 export * from "./GuildMessagesSearchResponse";
 export * from "./GuildPruneResponse";
+export * from "./GuildRecommendationsResponse";
 export * from "./GuildResponse";
 export * from "./GuildRolesResponse";
 export * from "./GuildStickersResponse";
@@ -31,6 +34,7 @@ export * from "./GuildVoiceRegionsResponse";
 export * from "./GuildWidgetJsonResponse";
 export * from "./GuildWidgetSettingsResponse";
 export * from "./InstanceDomainsResponse";
+export * from "./InstancePingResponse";
 export * from "./InstanceStatsResponse";
 export * from "./LimitsConfigurationResponse";
 export * from "./LocationMetadataResponse";
@@ -39,6 +43,7 @@ export * from "./OAuthAuthorizeResponse";
 export * from "./StickerPacksResponse";
 export * from "./Tenor";
 export * from "./TokenResponse";
+export * from "./UpdatesResponse";
 export * from "./UserNoteResponse";
 export * from "./UserProfileResponse";
 export * from "./UserRelationshipsResponse";