refactor(api): ♻️ Move more API routes to new OpenAPI format

api/api/v1/favourites/index.ts

@@ -1,15 +1,11 @@
-import {
-    apiRoute,
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { and, gt, gte, lt, sql } from "drizzle-orm";
 import { z } from "zod";
 import { Notes, RolePermissions } from "~/drizzle/schema";
+import { Note } from "~/packages/database-interface/note";
 import { Timeline } from "~/packages/database-interface/timeline";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -35,15 +31,37 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/favourites",
+    summary: "Get favourites",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: schemas.query,
+    },
+    responses: {
+        200: {
+            description: "Favourites",
+            content: {
+                "application/json": {
+                    schema: z.array(Note.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const { max_id, since_id, min_id, limit } =
-                context.req.valid("query");
+    app.openapi(route, async (context) => {
+        const { max_id, since_id, min_id, limit } = context.req.valid("query");
 
         const { user } = context.get("auth");
 
@@ -51,8 +69,7 @@ export default apiRoute((app) =>
             return context.json({ error: "Unauthorized" }, 401);
         }
 
-            const { objects: favourites, link } =
-                await Timeline.getNoteTimeline(
+        const { objects: favourites, link } = await Timeline.getNoteTimeline(
             and(
                 max_id ? lt(Notes.id, max_id) : undefined,
                 since_id ? gte(Notes.id, since_id) : undefined,
@@ -65,14 +82,11 @@ export default apiRoute((app) =>
         );
 
         return context.json(
-                await Promise.all(
-                    favourites.map(async (note) => note.toApi(user)),
-                ),
+            await Promise.all(favourites.map(async (note) => note.toApi(user))),
             200,
             {
                 Link: link,
             },
         );
-        },
-    ),
+    }),
 );

api/api/v1/follow_requests/:account_id/authorize.ts

@@ -1,10 +1,11 @@
-import { apiRoute, applyConfig, auth, handleZodError } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
 import { sendFollowAccept } from "~/classes/functions/user";
 import { RolePermissions } from "~/drizzle/schema";
 import { Relationship } from "~/packages/database-interface/relationship";
 import { User } from "~/packages/database-interface/user";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["POST"],
@@ -27,13 +28,44 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "post",
+    path: "/api/v1/follow_requests/{account_id}/authorize",
+    summary: "Authorize follow request",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        200: {
+            description: "Relationship",
+            content: {
+                "application/json": {
+                    schema: Relationship.schema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Account not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("param", schemas.param, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         const { user } = context.get("auth");
 
         if (!user) {
@@ -69,7 +101,6 @@ export default apiRoute((app) =>
             await sendFollowAccept(account, user);
         }
 
-            return context.json(foundRelationship.toApi());
-        },
-    ),
+        return context.json(foundRelationship.toApi(), 200);
+    }),
 );

api/api/v1/follow_requests/:account_id/reject.ts

@@ -1,10 +1,11 @@
-import { apiRoute, applyConfig, auth, handleZodError } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
 import { sendFollowReject } from "~/classes/functions/user";
 import { RolePermissions } from "~/drizzle/schema";
 import { Relationship } from "~/packages/database-interface/relationship";
 import { User } from "~/packages/database-interface/user";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["POST"],
@@ -27,13 +28,44 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "post",
+    path: "/api/v1/follow_requests/{account_id}/reject",
+    summary: "Reject follow request",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        200: {
+            description: "Relationship",
+            content: {
+                "application/json": {
+                    schema: Relationship.schema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Account not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("param", schemas.param, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         const { user } = context.get("auth");
 
         if (!user) {
@@ -69,7 +101,6 @@ export default apiRoute((app) =>
             await sendFollowReject(account, user);
         }
 
-            return context.json(foundRelationship.toApi());
-        },
-    ),
+        return context.json(foundRelationship.toApi(), 200);
+    }),
 );

api/api/v1/follow_requests/index.ts

@@ -1,15 +1,11 @@
-import {
-    apiRoute,
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { and, gt, gte, lt, sql } from "drizzle-orm";
 import { z } from "zod";
 import { RolePermissions, Users } from "~/drizzle/schema";
 import { Timeline } from "~/packages/database-interface/timeline";
+import { User } from "~/packages/database-interface/user";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -35,15 +31,37 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/follow_requests",
+    summary: "Get follow requests",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: schemas.query,
+    },
+    responses: {
+        200: {
+            description: "Follow requests",
+            content: {
+                "application/json": {
+                    schema: z.array(User.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const { max_id, since_id, min_id, limit } =
-                context.req.valid("query");
+    app.openapi(route, async (context) => {
+        const { max_id, since_id, min_id, limit } = context.req.valid("query");
 
         const { user } = context.get("auth");
 
@@ -70,6 +88,5 @@ export default apiRoute((app) =>
                 Link: link,
             },
         );
-        },
-    ),
+    }),
 );

api/api/v1/frontend/config/index.ts

@@ -1,4 +1,5 @@
 import { apiRoute, applyConfig } from "@/api";
+import { createRoute, z } from "@hono/zod-openapi";
 import { config } from "~/packages/config-manager";
 
 export const meta = applyConfig({
@@ -13,8 +14,24 @@ export const meta = applyConfig({
     route: "/api/v1/frontend/config",
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/frontend/config",
+    summary: "Get frontend config",
+    responses: {
+        200: {
+            description: "Frontend config",
+            content: {
+                "application/json": {
+                    schema: z.record(z.string(), z.any()).default({}),
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(meta.allowedMethods, meta.route, (context) => {
-        return context.json(config.frontend.settings);
+    app.openapi(route, (context) => {
+        return context.json(config.frontend.settings, 200);
     }),
 );

api/api/v1/instance/index.ts

@@ -1,5 +1,6 @@
 import { apiRoute, applyConfig, auth } from "@/api";
 import { proxyUrl } from "@/response";
+import { createRoute, z } from "@hono/zod-openapi";
 import { and, eq, isNull } from "drizzle-orm";
 import { Users } from "~/drizzle/schema";
 import manifest from "~/package.json";
@@ -20,12 +21,26 @@ export const meta = applyConfig({
     },
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/instance",
+    summary: "Get instance information",
+    middleware: [auth(meta.auth)],
+    responses: {
+        200: {
+            description: "Instance information",
+            content: {
+                // TODO: Add schemas for this response
+                "application/json": {
+                    schema: z.any(),
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         // Get software version from package.json
         const version = manifest.version;
 
@@ -101,6 +116,5 @@ export default apiRoute((app) =>
                 }[];
             };
         });
-        },
-    ),
+    }),
 );

api/api/v1/instance/privacy_policy.ts

@@ -1,5 +1,6 @@
 import { apiRoute, applyConfig, auth } from "@/api";
 import { renderMarkdownInPath } from "@/markdown";
+import { createRoute, z } from "@hono/zod-openapi";
 import { config } from "~/packages/config-manager";
 
 export const meta = applyConfig({
@@ -14,12 +15,28 @@ export const meta = applyConfig({
     },
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/instance/privacy_policy",
+    summary: "Get instance privacy policy",
+    middleware: [auth(meta.auth)],
+    responses: {
+        200: {
+            description: "Instance privacy policy",
+            content: {
+                "application/json": {
+                    schema: z.object({
+                        updated_at: z.string(),
+                        content: z.string(),
+                    }),
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         const { content, lastModified } = await renderMarkdownInPath(
             config.instance.privacy_policy_path ?? "",
             "This instance has not provided any privacy policy.",
@@ -29,6 +46,5 @@ export default apiRoute((app) =>
             updated_at: lastModified.toISOString(),
             content,
         });
-        },
-    ),
+    }),
 );

api/api/v1/instance/rules.ts

@@ -1,4 +1,5 @@
 import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute, z } from "@hono/zod-openapi";
 import { config } from "~/packages/config-manager";
 
 export const meta = applyConfig({
@@ -13,12 +14,31 @@ export const meta = applyConfig({
     },
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/instance/rules",
+    summary: "Get instance rules",
+    middleware: [auth(meta.auth)],
+    responses: {
+        200: {
+            description: "Instance rules",
+            content: {
+                "application/json": {
+                    schema: z.array(
+                        z.object({
+                            id: z.string(),
+                            text: z.string(),
+                            hint: z.string(),
+                        }),
+                    ),
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         return context.json(
             config.signups.rules.map((rule, index) => ({
                 id: String(index),
@@ -26,6 +46,5 @@ export default apiRoute((app) =>
                 hint: "",
             })),
         );
-        },
-    ),
+    }),
 );

api/api/v1/instance/tos.ts

@@ -1,5 +1,6 @@
 import { apiRoute, applyConfig, auth } from "@/api";
 import { renderMarkdownInPath } from "@/markdown";
+import { createRoute, z } from "@hono/zod-openapi";
 import { config } from "~/packages/config-manager";
 
 export const meta = applyConfig({
@@ -14,12 +15,28 @@ export const meta = applyConfig({
     },
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/instance/tos",
+    summary: "Get instance terms of service",
+    middleware: [auth(meta.auth)],
+    responses: {
+        200: {
+            description: "Instance terms of service",
+            content: {
+                "application/json": {
+                    schema: z.object({
+                        updated_at: z.string(),
+                        content: z.string(),
+                    }),
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         const { content, lastModified } = await renderMarkdownInPath(
             config.instance.tos_path ?? "",
             "This instance has not provided any terms of service.",
@@ -29,6 +46,5 @@ export default apiRoute((app) =>
             updated_at: lastModified.toISOString(),
             content,
         });
-        },
-    ),
+    }),
 );

api/api/v1/markers/index.ts

@@ -1,16 +1,11 @@
-import {
-    apiRoute,
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import type { Marker as ApiMarker } from "@versia/client/types";
 import { and, count, eq } from "drizzle-orm";
 import { z } from "zod";
 import { db } from "~/drizzle/db";
 import { Markers, RolePermissions } from "~/drizzle/schema";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET", "POST"],
@@ -29,24 +24,96 @@ export const meta = applyConfig({
 });
 
 export const schemas = {
+    markers: z.object({
+        home: z
+            .object({
+                last_read_id: z.string().regex(idValidator),
+                version: z.number(),
+                updated_at: z.string(),
+            })
+            .nullable()
+            .optional(),
+        notifications: z
+            .object({
+                last_read_id: z.string().regex(idValidator),
+                version: z.number(),
+                updated_at: z.string(),
+            })
+            .nullable()
+            .optional(),
+    }),
+};
+
+const routeGet = createRoute({
+    method: "get",
+    path: "/api/v1/markers",
+    summary: "Get markers",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
         query: z.object({
             "timeline[]": z
                 .array(z.enum(["home", "notifications"]))
                 .max(2)
                 .or(z.enum(["home", "notifications"]))
                 .optional(),
-        "home[last_read_id]": z.string().regex(idValidator).optional(),
-        "notifications[last_read_id]": z.string().regex(idValidator).optional(),
         }),
-};
+    },
+    responses: {
+        200: {
+            description: "Markers",
+            content: {
+                "application/json": {
+                    schema: schemas.markers,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
 
-export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+const routePost = createRoute({
+    method: "post",
+    path: "/api/v1/markers",
+    summary: "Update markers",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: z.object({
+            "home[last_read_id]": z.string().regex(idValidator).optional(),
+            "notifications[last_read_id]": z
+                .string()
+                .regex(idValidator)
+                .optional(),
+        }),
+    },
+    responses: {
+        200: {
+            description: "Markers",
+            content: {
+                "application/json": {
+                    schema: schemas.markers,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) => {
+    app.openapi(routeGet, async (context) => {
         const { "timeline[]": timelines } = context.req.valid("query");
         const { user } = context.get("auth");
 
@@ -56,10 +123,8 @@ export default apiRoute((app) =>
             return context.json({ error: "Unauthorized" }, 401);
         }
 
-            switch (context.req.method) {
-                case "GET": {
         if (!timeline) {
-                        return context.json({});
+            return context.json({}, 200);
         }
 
         const markers: ApiMarker = {
@@ -92,9 +157,7 @@ export default apiRoute((app) =>
                 markers.home = {
                     last_read_id: found.noteId,
                     version: totalCount[0].count,
-                                updated_at: new Date(
-                                    found.createdAt,
-                                ).toISOString(),
+                    updated_at: new Date(found.createdAt).toISOString(),
                 };
             }
         }
@@ -124,21 +187,24 @@ export default apiRoute((app) =>
                 markers.notifications = {
                     last_read_id: found.notificationId,
                     version: totalCount[0].count,
-                                updated_at: new Date(
-                                    found.createdAt,
-                                ).toISOString(),
+                    updated_at: new Date(found.createdAt).toISOString(),
                 };
             }
         }
 
-                    return context.json(markers);
-                }
+        return context.json(markers, 200);
+    });
 
-                case "POST": {
+    app.openapi(routePost, async (context) => {
         const {
             "home[last_read_id]": homeId,
             "notifications[last_read_id]": notificationsId,
         } = context.req.valid("query");
+        const { user } = context.get("auth");
+
+        if (!user) {
+            return context.json({ error: "Unauthorized" }, 401);
+        }
 
         const markers: ApiMarker = {
             home: undefined,
@@ -172,9 +238,7 @@ export default apiRoute((app) =>
             markers.home = {
                 last_read_id: homeId,
                 version: totalCount[0].count,
-                            updated_at: new Date(
-                                insertedMarker.createdAt,
-                            ).toISOString(),
+                updated_at: new Date(insertedMarker.createdAt).toISOString(),
             };
         }
 
@@ -205,15 +269,10 @@ export default apiRoute((app) =>
             markers.notifications = {
                 last_read_id: notificationsId,
                 version: totalCount[0].count,
-                            updated_at: new Date(
-                                insertedMarker.createdAt,
-                            ).toISOString(),
+                updated_at: new Date(insertedMarker.createdAt).toISOString(),
             };
         }
 
-                    return context.json(markers);
-                }
-            }
-        },
-    ),
-);
+        return context.json(markers, 200);
+    });
+});

api/api/v1/media/:id/index.ts

@@ -1,16 +1,11 @@
-import {
-    apiRoute,
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
 import { MediaManager } from "~/classes/media/media-manager";
 import { RolePermissions } from "~/drizzle/schema";
 import { config } from "~/packages/config-manager/index";
 import { Attachment } from "~/packages/database-interface/attachment";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET", "PUT"],
@@ -30,7 +25,7 @@ export const meta = applyConfig({
 
 export const schemas = {
     param: z.object({
-        id: z.string(),
+        id: z.string().uuid(),
     }),
     form: z.object({
         thumbnail: z.instanceof(File).optional(),
@@ -42,22 +37,88 @@ export const schemas = {
     }),
 };
 
-export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("param", schemas.param, handleZodError),
-        zValidator("form", schemas.form, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const { id } = context.req.valid("param");
+const routePut = createRoute({
+    method: "put",
+    path: "/api/v1/media/{id}",
+    summary: "Update media",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+        body: {
+            content: {
+                "multipart/form-data": {
+                    schema: schemas.form,
+                },
+            },
+        },
+    },
+    responses: {
+        204: {
+            description: "Media updated",
+            content: {
+                "application/json": {
+                    schema: Attachment.schema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Media not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
 
-            if (!id.match(idValidator)) {
-                return context.json(
-                    { error: "Invalid ID, must be of type UUIDv7" },
-                    404,
-                );
-            }
+const routeGet = createRoute({
+    method: "get",
+    path: "/api/v1/media/{id}",
+    summary: "Get media",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        200: {
+            description: "Media",
+            content: {
+                "application/json": {
+                    schema: Attachment.schema,
+                },
+            },
+        },
+        404: {
+            description: "Media not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) => {
+    app.openapi(routePut, async (context) => {
+        const { id } = context.req.valid("param");
 
         const attachment = await Attachment.fromId(id);
 
@@ -65,16 +126,7 @@ export default apiRoute((app) =>
             return context.json({ error: "Media not found" }, 404);
         }
 
-            switch (context.req.method) {
-                case "GET": {
-                    if (attachment.data.url) {
-                        return context.json(attachment.toApi());
-                    }
-                    return context.newResponse(null, 206);
-                }
-                case "PUT": {
-                    const { description, thumbnail } =
-                        context.req.valid("form");
+        const { description, thumbnail } = context.req.valid("form");
 
         let thumbnailUrl = attachment.data.thumbnailUrl;
 
@@ -85,8 +137,7 @@ export default apiRoute((app) =>
             thumbnailUrl = Attachment.getUrl(path);
         }
 
-                    const descriptionText =
-                        description || attachment.data.description;
+        const descriptionText = description || attachment.data.description;
 
         if (
             descriptionText !== attachment.data.description ||
@@ -97,14 +148,21 @@ export default apiRoute((app) =>
                 thumbnailUrl,
             });
 
-                        return context.json(attachment.toApi());
+            return context.json(attachment.toApi(), 204);
         }
 
-                    return context.json(attachment.toApi());
-                }
+        return context.json(attachment.toApi(), 204);
+    });
+
+    app.openapi(routeGet, async (context) => {
+        const { id } = context.req.valid("param");
+
+        const attachment = await Attachment.fromId(id);
+
+        if (!attachment) {
+            return context.json({ error: "Media not found" }, 404);
         }
 
-            return context.json({ error: "Method not allowed" }, 405);
-        },
-    ),
-);
+        return context.json(attachment.toApi(), 200);
+    });
+});

api/api/v1/media/index.ts

@@ -1,11 +1,12 @@
-import { apiRoute, applyConfig, auth, handleZodError } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import sharp from "sharp";
 import { z } from "zod";
 import { MediaManager } from "~/classes/media/media-manager";
 import { RolePermissions } from "~/drizzle/schema";
 import { config } from "~/packages/config-manager/index";
 import { Attachment } from "~/packages/database-interface/attachment";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["POST"],
@@ -35,13 +36,58 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "post",
+    path: "/api/v1/media",
+    summary: "Upload media",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        body: {
+            content: {
+                "multipart/form-data": {
+                    schema: schemas.form,
+                },
+            },
+        },
+    },
+    responses: {
+        200: {
+            description: "Attachment",
+            content: {
+                "application/json": {
+                    schema: Attachment.schema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        413: {
+            description: "File too large",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        415: {
+            description: "Disallowed file type",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("form", schemas.form, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
+    app.openapi(route, async (context) => {
         const { file, thumbnail, description } = context.req.valid("form");
 
         if (file.size > config.validation.max_media_size) {
@@ -57,7 +103,7 @@ export default apiRoute((app) =>
             config.validation.enforce_mime_types &&
             !config.validation.allowed_mime_types.includes(file.type)
         ) {
-                return context.json({ error: "Invalid file type" }, 415);
+            return context.json({ error: "Disallowed file type" }, 415);
         }
 
         const sha256 = new Bun.SHA256();
@@ -96,7 +142,6 @@ export default apiRoute((app) =>
 
         // TODO: Add job to process videos and other media
 
-            return context.json(newAttachment.toApi());
-        },
-    ),
+        return context.json(newAttachment.toApi(), 200);
+    }),
 );

api/api/v1/mutes/index.ts

@@ -1,15 +1,11 @@
-import {
-    apiRoute,
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { and, gt, gte, lt, sql } from "drizzle-orm";
 import { z } from "zod";
 import { RolePermissions, Users } from "~/drizzle/schema";
 import { Timeline } from "~/packages/database-interface/timeline";
+import { User } from "~/packages/database-interface/user";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -36,15 +32,37 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/mutes",
+    summary: "Get muted users",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: schemas.query,
+    },
+    responses: {
+        200: {
+            description: "Muted users",
+            content: {
+                "application/json": {
+                    schema: z.array(User.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const { max_id, since_id, limit, min_id } =
-                context.req.valid("query");
+    app.openapi(route, async (context) => {
+        const { max_id, since_id, limit, min_id } = context.req.valid("query");
         const { user } = context.get("auth");
 
         if (!user) {
@@ -69,6 +87,5 @@ export default apiRoute((app) =>
                 Link: link,
             },
         );
-        },
-    ),
+    }),
 );

packages/database-interface/attachment.ts

@@ -1,8 +1,5 @@
 import { proxyUrl } from "@/response";
-import type {
-    AsyncAttachment as ApiAsyncAttachment,
-    Attachment as ApiAttachment,
-} from "@versia/client/types";
+import type { Attachment as ApiAttachment } from "@versia/client/types";
 import type { ContentFormat } from "@versia/federation/types";
 import {
     type InferInsertModel,
@@ -212,7 +209,7 @@ export class Attachment extends BaseInterface<typeof Attachments> {
         };
     }
 
-    public toApi(): ApiAttachment | ApiAsyncAttachment {
+    public toApi(): ApiAttachment {
         return {
             id: this.data.id,
             type: this.getMastodonType(),