Merge pull request #3 from Aditya-Jyoti/master

feat: Add support for swagger

README.md

@@ -36,13 +36,64 @@ The all in one hono api template with prisma, postgresql and minio s3 bucket set
 │   │   └── s3-client.ts
 │   ├── routes
 │   │   └── auth
+│   │       ├── index.ts
+│   │       └── routes.ts
 │   └── utils
 │       └── passwords.ts
 └── tsconfig.json
 ```
 
 ## Whats included
 
+### Swagger Docs served at /docs
+
+1. Each route should be inside `/src/routes/<route-folder>/`
+2. Each `/<route-folder>/` should include 2 files
+
+   1. `routes.ts`
+
+      - here define the openapi specs for all your routes in this format
+
+        ```ts
+        export const <route-name> = createRoute({
+          method: "",
+          path: "/<route-name>",
+          request: {
+            query: z.object({
+            }),
+          },
+          responses: {
+            200: {
+              description: "",
+              content: {
+                "application/json": {
+                  schema: z.object({}).openapi("<route-name>Response"),
+                },
+              },
+            },
+            ...
+          },
+        });
+        ```
+
+   2. `index.ts`
+
+      - import your route specs here and define functionality
+
+        ```ts
+        const <main-router-name>Router = new OpenAPIHono();
+
+        <main-router-name>Router.openapi(<imported-router>, async (ctx) => {
+          const {  } = ctx.req.valid("query");
+
+          return new Response("<description>", {
+            status: ,
+          });
+        });
+        ```
+
+3. include defined router in `/src/index.ts`
+
 ### Prisma Role Base Auth
 
 The project includes a pre-configured Prisma schema for role-based authentication and user management. The schema defines two main models:
@@ -108,15 +159,17 @@ Retrieves a document from the MinIO server using its unique document ID.
   `docId (string)`: The unique ID of the document.
 
 - Returns:
+
   - `Promise<{ data: Buffer; contentType: string; }>`: An object containing:
+
     - `data (Buffer)`: The document's content.
     - `contentType (string)`: The MIME type of the document.
 
-```ts
-const doc = await readDocument(docId);
-console.log("Document content type:", doc.contentType);
-console.log("Document data:", doc.data.toString());
-```
+    ```ts
+    const doc = await readDocument(docId);
+    console.log("Document content type:", doc.contentType);
+    console.log("Document data:", doc.data.toString());
+    ```
 
 3. `deleteDocument(docId: string): Promise<void>`
 
@@ -127,12 +180,13 @@ Deletes a document from the MinIO server using its unique document ID.
   - `docId (string)`: The unique ID of the document to delete.
 
 - Returns:
+
   - `Promise<void>`: Resolves once the document is successfully deleted.
 
-```ts
-await deleteDocument(docId);
-console.log("Document deleted successfully");
-```
+    ```ts
+    await deleteDocument(docId);
+    console.log("Document deleted successfully");
+    ```
 
 ### Auth Routes
 
@@ -143,15 +197,16 @@ The authentication module provides routes for user login and registration, utili
 Authenticates a user and returns a JWT for accessing protected resources.
 
 - **Request Body (JSON)**
+
   - `email (string)`: The user's email. Must be a valid email address.
   - `password (string)`: The user's password. Must be at least 8 characters.
 
-```json
-{
-  "email": "[email protected]",
-  "password": "securepassword"
-}
-```
+    ```json
+    {
+      "email": "[email protected]",
+      "password": "securepassword"
+    }
+    ```
 
 - **Responses**
   - 200 OK
@@ -166,19 +221,20 @@ Authenticates a user and returns a JWT for accessing protected resources.
 Registers a new user by creating entries in the `Auth` and `User` models.
 
 - **Request Body (JSON)**
+
   - `email (string)`: The user's email. Must be a valid email address.
   - `password (string)`: The user's password. Must be at least 8 characters.
   - `name (string)`: Full name of the user.
   - `role (string)`: Role of the user (ADMIN or USER).
 
-```json
-{
-  "name": "John Doe",
-  "role": "USER",
-  "email": "[email protected]",
-  "password": "securepassword"
-}
-```
+    ```json
+    {
+      "name": "John Doe",
+      "role": "USER",
+      "email": "[email protected]",
+      "password": "securepassword"
+    }
+    ```
 
 - **Responses**
   - 201 Created

package.json

@@ -11,7 +11,8 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.13.7",
-    "@hono/zod-validator": "^0.4.2",
+    "@hono/swagger-ui": "^0.5.0",
+    "@hono/zod-openapi": "^0.18.3",
     "@prisma/client": "^6.1.0",
     "hono": "^4.6.14",
     "jsonwebtoken": "^9.0.2",
@@ -34,7 +35,6 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1",
-    "uuid": "^11.0.3",
-    "zod": "^3.24.1"
+    "uuid": "^11.0.3"
   }
 }

src/index.ts

@@ -1,9 +1,10 @@
 import { serve } from "@hono/node-server";
-import { Hono } from "hono";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { swaggerUI } from "@hono/swagger-ui";
 
 import authRouter from "./routes/auth/index.js";
 
-const app = new Hono();
+const app = new OpenAPIHono();
 
 app.route("/auth", authRouter);
 
@@ -14,6 +15,16 @@ app.get("/", (c) => {
 const port = 3000;
 console.log(`Server is running on http://localhost:${port}`);
 
+app.doc("/openapi", {
+  openapi: "3.0.0",
+  info: {
+    version: "0.0.1",
+    title: "Backend for a hackathon management system",
+  },
+});
+
+app.get("/docs", swaggerUI({ url: "/openapi" }));
+
 serve({
   fetch: app.fetch,
   port,