feat: add openapi and swagger for documentation

Author: WillACosta

.gitignore

@@ -1,4 +1,5 @@
 docs/examples
 node_modules/
 .env
-*.pdf
+*.pdf
+dist/

.vscode/settings.json

@@ -4,6 +4,7 @@
     "dataproviders",
     "gemini",
     "nodenext",
+    "openapi",
     "predev",
     "prestart",
     "usecases"

README.md

@@ -2,7 +2,9 @@
 
 This is an Express service written in [TypeScript](https://www.typescriptlang.org/) that provides authorization functionality and includes gen-AI features, using RAG concepts, vector database and implements AI memory history with Redis DB.
 
-> 🌱 This project is under development.
+<center>
+  <img src="docs/docs-screenshot.jpeg" alt="Swagger UI screenshot">
+</center>
 
 ## Resources
 
@@ -15,6 +17,7 @@ This is an Express service written in [TypeScript](https://www.typescriptlang.or
 - [Docker](https://docs.docker.com/) Containers for setting up environment.
 - [Redis](https://redis.io/) database for storing AI messages.
 - [ZOD](https://zod.dev/) as body parameters validation.
+- Automated [OpenAPI](https://www.openapis.org/what-is-openapi) specifications using [JsDocs](https://jsdoc.app/) and [Swagger UI](https://swagger.io/tools/swagger-ui/) for generating documentation.
 
 ## Project Structure
 
@@ -79,4 +82,12 @@ cp .env.example .env
 docker compose up --build
 ```
 
-> The application will be available at `http://localhost:3000`.
+> The application will be available at `http://localhost:3000`.<br>
+
+## Documentation
+
+The documentation process is automated using `swagger-ui-express` and `swagger-jsdoc` libraries, on each application route definition you will find a comment with the necessary specifications for that route in particular.
+
+During the build process the application will handle the route comments and generate the final `OpenApi` specification for the `Swagger UI`.
+
+After that you will be able to access: `localhost:3000/docs` in your browser and see the docs.

docs/docs-screenshot.jpeg

@@ -0,0 +1,39 @@
+Generate the JSDocs comments using OpenAPI for the following API specs:
+
+```yaml
+endpoint name: /users/all
+# path parameter type: string
+method: GET
+request body: {
+  "name": "John Doe",
+	"email": "[email protected]",
+}
+summary: Returns all users
+200_response: {
+	"success": true,
+	"data": [
+    {
+      "id": "367b2539-bef4-412b-b94d-c9d2178dcdaa",
+      "name": "John Doe",
+      "email": "[email protected]",
+      "createdAt": "2024-09-30T21:04:18.656Z"
+    }
+  ]
+}
+# 400_response: {
+#   "success": false,
+#   "error": {
+#     "message": [
+#       "Invalid email address",
+# 			"name field is required"
+#     ]
+#   }
+# }
+headers: {
+  "Content-Type": "application/json",
+  "Authorization": "Bearer <token>"
+}
+```
+
+More context: I'm using `swagger-ui-express` and `swagger-jsdoc` libraries to setup the Swagger documentation.
+Give me only the response, without explanations.

docs/prompts/generate-openapi-jsdocs.md

@@ -1,7 +1,7 @@
 {
   "name": "genai-langchain-api",
   "version": "1.0.0",
-  "description": "This is an Express service that provides authorization functionality and includes gen-AI features.",
+  "description": "This is an Express service that provides authorization functionality and includes gen-AI features using RAG, Redis, Postgres, and Langchain.",
   "scripts": {
     "prestart": "node dynamic-url-config.js",
     "predev": "node dynamic-url-config.js",
@@ -30,6 +30,8 @@
     "multer": "1.4.5-lts.1",
     "pdf-parse": "^1.1.1",
     "redis": "^4.7.0",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -38,6 +40,8 @@
     "@types/jsonwebtoken": "^9.0.7",
     "@types/multer": "^1.4.12",
     "@types/node": "^22.5.5",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.6",
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
     "nodemon": "^3.1.4",