docs: Add asset APIs to the openapi spec

Author: MohamedBassem

packages/open-api/index.ts

@@ -4,6 +4,7 @@ import {
   OpenAPIRegistry,
 } from "@asteasolutions/zod-to-openapi";
 
+import { registry as assetsRegistry } from "./lib/assets";
 import { registry as bookmarksRegistry } from "./lib/bookmarks";
 import { registry as commonRegistry } from "./lib/common";
 import { registry as highlightsRegistry } from "./lib/highlights";
@@ -19,6 +20,7 @@ function getOpenApiDocumentation() {
     tagsRegistry,
     highlightsRegistry,
     userRegistry,
+    assetsRegistry,
   ]);
 
   const generator = new OpenApiGeneratorV3(registry.definitions);

packages/open-api/karakeep-openapi-spec.json

@@ -25,10 +25,6 @@
       }
     },
     "schemas": {
-      "AssetId": {
-        "type": "string",
-        "example": "ieidlxygmwj87oxz5hxttoc8"
-      },
       "BookmarkId": {
         "type": "string",
         "example": "ieidlxygmwj87oxz5hxttoc8"
@@ -45,6 +41,10 @@
         "type": "string",
         "example": "ieidlxygmwj87oxz5hxttoc8"
       },
+      "AssetId": {
+        "type": "string",
+        "example": "ieidlxygmwj87oxz5hxttoc8"
+      },
       "Bookmark": {
         "type": "object",
         "properties": {
@@ -488,17 +488,33 @@
           "highlights",
           "nextCursor"
         ]
-      }
-    },
-    "parameters": {
-      "AssetId": {
-        "schema": {
-          "$ref": "#/components/schemas/AssetId"
+      },
+      "Asset": {
+        "type": "object",
+        "properties": {
+          "assetId": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "size": {
+            "type": "number"
+          },
+          "fileName": {
+            "type": "string"
+          }
         },
-        "required": true,
-        "name": "assetId",
-        "in": "path"
+        "required": [
+          "assetId",
+          "contentType",
+          "size",
+          "fileName"
+        ]
       },
+      "File to be uploaded": {}
+    },
+    "parameters": {
       "BookmarkId": {
         "schema": {
           "$ref": "#/components/schemas/BookmarkId"
@@ -530,6 +546,14 @@
         "required": true,
         "name": "highlightId",
         "in": "path"
+      },
+      "AssetId": {
+        "schema": {
+          "$ref": "#/components/schemas/AssetId"
+        },
+        "required": true,
+        "name": "assetId",
+        "in": "path"
       }
     }
   },
@@ -3031,6 +3055,71 @@
           }
         }
       }
+    },
+    "/assets": {
+      "post": {
+        "description": "Upload a new asset",
+        "summary": "Upload a new asset",
+        "tags": [
+          "Assets"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "The data to create the asset with.",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "$ref": "#/components/schemas/File to be uploaded"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Details about the created asset",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Asset"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/assets/{assetId}": {
+      "get": {
+        "description": "Get asset by its id",
+        "summary": "Get a single asset",
+        "tags": [
+          "Assets"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AssetId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Asset content. Content type is determined by the asset type."
+          }
+        }
+      }
     }
   }
 }

packages/open-api/lib/assets.ts

@@ -0,0 +1,77 @@
+import {
+  extendZodWithOpenApi,
+  OpenAPIRegistry,
+} from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+
+import { BearerAuth } from "./common";
+
+export const registry = new OpenAPIRegistry();
+extendZodWithOpenApi(z);
+
+export const AssetIdSchema = registry.registerParameter(
+  "AssetId",
+  z.string().openapi({
+    param: {
+      name: "assetId",
+      in: "path",
+    },
+    example: "ieidlxygmwj87oxz5hxttoc8",
+  }),
+);
+
+registry.registerPath({
+  method: "post",
+  path: "/assets",
+  description: "Upload a new asset",
+  summary: "Upload a new asset",
+  tags: ["Assets"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    body: {
+      description: "The data to create the asset with.",
+      content: {
+        "multipart/form-data": {
+          schema: z.object({
+            file: z.instanceof(File).openapi("File to be uploaded"),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Details about the created asset",
+      content: {
+        "application/json": {
+          schema: z
+            .object({
+              assetId: z.string(),
+              contentType: z.string(),
+              size: z.number(),
+              fileName: z.string(),
+            })
+            .openapi("Asset"),
+        },
+      },
+    },
+  },
+});
+
+registry.registerPath({
+  method: "get",
+  path: "/assets/{assetId}",
+  description: "Get asset by its id",
+  summary: "Get a single asset",
+  tags: ["Assets"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({ assetId: AssetIdSchema }),
+  },
+  responses: {
+    200: {
+      description:
+        "Asset content. Content type is determined by the asset type.",
+    },
+  },
+});

packages/open-api/lib/bookmarks.ts

@@ -13,6 +13,7 @@ import {
   zUpdateBookmarksRequestSchema,
 } from "@karakeep/shared/types/bookmarks";
 
+import { AssetIdSchema } from "./assets";
 import { BearerAuth } from "./common";
 import { ErrorSchema } from "./errors";
 import { HighlightSchema } from "./highlights";
@@ -27,17 +28,6 @@ import { TagIdSchema } from "./tags";
 export const registry = new OpenAPIRegistry();
 extendZodWithOpenApi(z);
 
-export const AssetIdSchema = registry.registerParameter(
-  "AssetId",
-  z.string().openapi({
-    param: {
-      name: "assetId",
-      in: "path",
-    },
-    example: "ieidlxygmwj87oxz5hxttoc8",
-  }),
-);
-
 export const BookmarkIdSchema = registry.registerParameter(
   "BookmarkId",
   z.string().openapi({