oapi: root level routes

src/api/routes/discoverable-guilds.ts

@@ -16,49 +16,61 @@
 	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(
-	const { offset, limit, categories } = req.query;
+	"/",
-	const showAllGuilds = Config.get().guild.discovery.showAllGuilds;
+	route({
-	const configLimit = Config.get().guild.discovery.limit;
+		responses: {
-	let guilds;
+			200: {
-	if (categories == undefined) {
+				body: "DiscoverableGuildsResponse",
-		guilds = showAllGuilds
+			},
-			? await Guild.find({ take: Math.abs(Number(limit || configLimit)) })
+		},
-			: await Guild.find({
+	}),
-					where: { features: Like(`%DISCOVERABLE%`) },
+	async (req: Request, res: Response) => {
-					take: Math.abs(Number(limit || configLimit)),
+		const { offset, limit, categories } = req.query;
-			  });
+		const showAllGuilds = Config.get().guild.discovery.showAllGuilds;
-	} else {
+		const configLimit = Config.get().guild.discovery.limit;
-		guilds = showAllGuilds
+		let guilds;
-			? await Guild.find({
+		if (categories == undefined) {
-					where: { primary_category_id: categories.toString() },
+			guilds = showAllGuilds
-					take: Math.abs(Number(limit || configLimit)),
+				? await Guild.find({
-			  })
+						take: Math.abs(Number(limit || configLimit)),
-			: await Guild.find({
+				  })
-					where: {
+				: await Guild.find({
-						primary_category_id: categories.toString(),
+						where: { features: Like(`%DISCOVERABLE%`) },
-						features: Like("%DISCOVERABLE%"),
+						take: Math.abs(Number(limit || configLimit)),
-					},
+				  });
-					take: Math.abs(Number(limit || configLimit)),
+		} else {
-			  });
+			guilds = showAllGuilds
-	}
+				? await Guild.find({
+						where: { primary_category_id: categories.toString() },
+						take: Math.abs(Number(limit || configLimit)),
+				  })
+				: await Guild.find({
+						where: {
+							primary_category_id: categories.toString(),
+							features: Like("%DISCOVERABLE%"),
+						},
+						take: Math.abs(Number(limit || configLimit)),
+				  });
+		}
 
-	const total = guilds ? guilds.length : undefined;
+		const total = guilds ? guilds.length : undefined;
 
-	res.send({
+		res.send({
-		total: total,
+			total: total,
-		guilds: guilds,
+			guilds: guilds,
-		offset: Number(offset || Config.get().guild.discovery.offset),
+			offset: Number(offset || Config.get().guild.discovery.offset),
-		limit: Number(limit || configLimit),
+			limit: Number(limit || configLimit),
-	});
+		});
-});
+	},
+);
 
 export default router;

src/api/routes/discovery.ts

@@ -16,24 +16,34 @@
 	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(
-	// TODO:
+	"/categories",
-	// Get locale instead
+	route({
+		responses: {
+			200: {
+				body: "DiscoveryCategoriesResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
+		// TODO:
+		// Get locale instead
 
-	// const { locale, primary_only } = req.query;
+		// const { locale, primary_only } = req.query;
-	const { primary_only } = req.query;
+		const { primary_only } = req.query;
 
-	const out = primary_only
+		const out = primary_only
-		? await Categories.find()
+			? await Categories.find()
-		: await Categories.find({ where: { is_primary: true } });
+			: await Categories.find({ where: { is_primary: true } });
 
-	res.send(out);
+		res.send(out);
-});
+	},
+);
 
 export default router;

src/api/routes/download.ts

@@ -16,32 +16,43 @@
 	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(
-	const { platform } = req.query;
+	"/",
-
+	route({
-	if (!platform)
+		responses: {
-		throw FieldErrors({
+			302: {},
-			platform: {
+			404: {
-				code: "BASE_TYPE_REQUIRED",
+				body: "APIErrorResponse",
-				message: req.t("common:field.BASE_TYPE_REQUIRED"),
 			},
+		},
+	}),
+	async (req: Request, res: Response) => {
+		const { platform } = req.query;
+
+		if (!platform)
+			throw FieldErrors({
+				platform: {
+					code: "BASE_TYPE_REQUIRED",
+					message: req.t("common:field.BASE_TYPE_REQUIRED"),
+				},
+			});
+
+		const release = await Release.findOneOrFail({
+			where: {
+				enabled: true,
+				platform: platform as string,
+			},
+			order: { pub_date: "DESC" },
 		});
 
-	const release = await Release.findOneOrFail({
+		res.redirect(release.url);
-		where: {
+	},
-			enabled: true,
+);
-			platform: platform as string,
-		},
-		order: { pub_date: "DESC" },
-	});
-
-	res.redirect(release.url);
-});
 
 export default router;

src/api/routes/guild-recommendations.ts

@@ -16,34 +16,44 @@
 	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(
-	// const { limit, personalization_disabled } = req.query;
+	"/",
-	const { limit } = req.query;
+	route({
-	const showAllGuilds = Config.get().guild.discovery.showAllGuilds;
+		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;
 
-	const genLoadId = (size: number) =>
+		const genLoadId = (size: number) =>
-		[...Array(size)]
+			[...Array(size)]
-			.map(() => Math.floor(Math.random() * 16).toString(16))
+				.map(() => Math.floor(Math.random() * 16).toString(16))
-			.join("");
+				.join("");
 
-	const guilds = showAllGuilds
+		const guilds = showAllGuilds
-		? await Guild.find({ take: Math.abs(Number(limit || 24)) })
+			? await Guild.find({ take: Math.abs(Number(limit || 24)) })
-		: await Guild.find({
+			: await Guild.find({
-				where: { features: Like("%DISCOVERABLE%") },
+					where: { features: Like("%DISCOVERABLE%") },
-				take: Math.abs(Number(limit || 24)),
+					take: Math.abs(Number(limit || 24)),
-		  });
+			  });
-	res.send({
+		res.send({
-		recommended_guilds: guilds,
+			recommended_guilds: guilds,
-		load_id: `server_recs/${genLoadId(32)}`,
+			load_id: `server_recs/${genLoadId(32)}`,
-	}).status(200);
+		}).status(200);
-});
+	},
+);
 
 export default router;

src/api/routes/ping.ts

@@ -16,29 +16,39 @@
 	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(
-	const { general } = Config.get();
+	"/",
-	res.send({
+	route({
-		ping: "pong!",
+		responses: {
-		instance: {
+			200: {
-			id: general.instanceId,
+				body: "InstancePingResponse",
-			name: general.instanceName,
+			},
-			description: general.instanceDescription,
-			image: general.image,
-
-			correspondenceEmail: general.correspondenceEmail,
-			correspondenceUserID: general.correspondenceUserID,
-
-			frontPage: general.frontPage,
-			tosPage: general.tosPage,
 		},
-	});
+	}),
-});
+	(req: Request, res: Response) => {
+		const { general } = Config.get();
+		res.send({
+			ping: "pong!",
+			instance: {
+				id: general.instanceId,
+				name: general.instanceName,
+				description: general.instanceDescription,
+				image: general.image,
+
+				correspondenceEmail: general.correspondenceEmail,
+				correspondenceUserID: general.correspondenceUserID,
+
+				frontPage: general.frontPage,
+				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(
-	// TODO:
+	"/",
-	res.sendStatus(204);
+	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,37 +16,53 @@
 	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(
-	const platform = req.query.platform;
+	"/",
-
+	route({
-	if (!platform)
+		responses: {
-		throw FieldErrors({
+			200: {
-			platform: {
+				body: "UpdatesResponse",
-				code: "BASE_TYPE_REQUIRED",
-				message: req.t("common:field.BASE_TYPE_REQUIRED"),
 			},
+			400: {
+				body: "APIErrorResponse",
+			},
+			404: {
+				body: "APIErrorResponse",
+			},
+		},
+	}),
+	async (req: Request, res: Response) => {
+		const platform = req.query.platform;
+
+		if (!platform)
+			throw FieldErrors({
+				platform: {
+					code: "BASE_TYPE_REQUIRED",
+					message: req.t("common:field.BASE_TYPE_REQUIRED"),
+				},
+			});
+
+		const release = await Release.findOneOrFail({
+			where: {
+				enabled: true,
+				platform: platform as string,
+			},
+			order: { pub_date: "DESC" },
 		});
 
-	const release = await Release.findOneOrFail({
+		res.json({
-		where: {
+			name: release.name,
-			enabled: true,
+			pub_date: release.pub_date,
-			platform: platform as string,
+			url: release.url,
-		},
+			notes: release.notes,
-		order: { pub_date: "DESC" },
+		});
-	});
+	},
-
+);
-	res.json({
-		name: release.name,
-		pub_date: release.pub_date,
-		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";