oapi: root level routes

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";