initiated openapi swagger integration, added license

Author: muneebhashone

README.md

@@ -24,14 +24,12 @@ Before you get started, make sure you have the following installed on your machi
      ```sh
      docker compose up -d
      ```
-
 2. **Install Dependencies**:
 
    - Use pnpm to install all the necessary dependencies:
      ```sh
      pnpm i
      ```
-
 3. **Configure Environment Variables**:
 
    - Create a `.env` file in the root directory.
@@ -83,3 +81,7 @@ Before you get started, make sure you have the following installed on your machi
 ## Contributions
 
 Feel free to contribute to this project by submitting issues or pull requests. Let's build something amazing together!
+
+## **License**
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

openapi-docs.yml

@@ -0,0 +1,58 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: My API
+  description: This is the API
+servers:
+  - url: v1
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    UserId:
+      type: string
+      example: "1212121"
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "1212121"
+        name:
+          type: string
+          example: John Doe
+        age:
+          type: number
+          example: 42
+      required:
+        - id
+        - name
+        - age
+  parameters:
+    UserId:
+      schema:
+        $ref: "#/components/schemas/UserId"
+      required: true
+      name: id
+      in: path
+paths:
+  /users/{id}:
+    get:
+      description: Get user data by its id
+      summary: Get a single user
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/UserId"
+      responses:
+        "200":
+          description: Object with user data.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "204":
+          description: No content - successful operation

package.json

@@ -47,6 +47,7 @@
     "typescript-eslint": "^7.11.0"
   },
   "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^7.1.1",
     "@aws-sdk/client-s3": "^3.606.0",
     "@bull-board/api": "^5.19.0",
     "@bull-board/express": "^5.16.0",
@@ -88,7 +89,9 @@
     "pino-pretty": "^11.1.0",
     "redis": "^4.6.11",
     "socket.io": "^4.7.5",
+    "swagger-ui-express": "^5.0.1",
     "validator": "^13.12.0",
+    "yaml": "^2.5.0",
     "zod": "^3.21.4"
   },
   "author": "",

pnpm-lock.yaml

@@ -19,9 +19,19 @@ import { connectDatabase } from './lib/database';
 import { useSocketIo } from './lib/realtime.server';
 import path from 'path';
 
+import swaggerUi from 'swagger-ui-express';
+import YAML from 'yaml';
+import fs from 'node:fs/promises';
+
 const boostrapServer = async () => {
   await connectDatabase();
 
+  const file = await fs.readFile(
+    path.join(process.cwd(), 'openapi-docs.yml'),
+    'utf8',
+  );
+  const swaggerDocument = YAML.parse(file);
+
   const app = express();
 
   app.set('trust proxy', true);
@@ -61,15 +71,10 @@ const boostrapServer = async () => {
       store: redisStore,
     }),
   );
+
   // Middleware to serve static files
   app.use(express.static(path.join(__dirname, '..', 'public')));
 
-  // Route to send static file via response to socket.io
-  app.get('/socket', (_, res) => {
-    const filePath = path.join(__dirname, '..', 'public', 'index.html');
-    res.sendFile(filePath);
-  });
-
   app.use(cookieParser());
 
   app.use(compression());
@@ -81,6 +86,7 @@ const boostrapServer = async () => {
   }
 
   app.use('/api', apiRoutes);
+  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
 
   const serverAdapter = new ExpressAdapter();
   serverAdapter.setBasePath('/admin/queues');

public/index.html renamed to public/socket.html

@@ -0,0 +1,94 @@
+import {
+  OpenApiGeneratorV3,
+  OpenAPIRegistry,
+  extendZodWithOpenApi,
+} from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+import * as yaml from 'yaml';
+import * as fs from 'fs';
+
+extendZodWithOpenApi(z);
+
+const registry = new OpenAPIRegistry();
+
+const UserIdSchema = registry.registerParameter(
+  'UserId',
+  z.string().openapi({
+    param: {
+      name: 'id',
+      in: 'path',
+    },
+    example: '1212121',
+  }),
+);
+const UserSchema = z
+  .object({
+    id: z.string().openapi({
+      example: '1212121',
+    }),
+    name: z.string().openapi({
+      example: 'John Doe',
+    }),
+    age: z.number().openapi({
+      example: 42,
+    }),
+  })
+  .openapi('User');
+
+const bearerAuth = registry.registerComponent('securitySchemes', 'bearerAuth', {
+  type: 'http',
+  scheme: 'bearer',
+  bearerFormat: 'JWT',
+});
+
+registry.registerPath({
+  method: 'get',
+  path: '/users/{id}',
+  description: 'Get user data by its id',
+  summary: 'Get a single user',
+  security: [{ [bearerAuth.name]: [] }],
+  request: {
+    params: z.object({ id: UserIdSchema }),
+  },
+  responses: {
+    200: {
+      description: 'Object with user data.',
+      content: {
+        'application/json': {
+          schema: UserSchema,
+        },
+      },
+    },
+    204: {
+      description: 'No content - successful operation',
+    },
+  },
+});
+
+function getOpenApiDocumentation() {
+  const generator = new OpenApiGeneratorV3(registry.definitions);
+
+  return generator.generateDocument({
+    openapi: '3.0.0',
+    info: {
+      version: '1.0.0',
+      title: 'My API',
+      description: 'This is the API',
+    },
+    servers: [{ url: 'v1' }],
+  });
+}
+
+function writeDocumentation() {
+  // OpenAPI JSON
+  const docs = getOpenApiDocumentation();
+
+  // YAML equivalent
+  const fileContent = yaml.stringify(docs);
+
+  fs.writeFileSync(`${__dirname}/openapi-docs.yml`, fileContent, {
+    encoding: 'utf-8',
+  });
+}
+
+writeDocumentation();