docs: improve readme and api docs

Author: WillACosta

README.md

@@ -41,14 +41,18 @@ modules: application features
       utils: class and constant utilities for this module
 ```
 
-### Search In Document Flow
+### Search In Documents Flow
 
-The search in document endpoint is the most complex of this application, it uses RAG concepts to break down the provided
-PDF document into small chunks and use it as context to the follow-up questions. Also, it uses Redis to store
-and retrieve chat history during user's session.
+To perform a search in documents and ask questions about them, we have two endpoints for that:
 
-> A possible improvement, is to have a separated endpoint for uploading documents and another one for handling questions
-> to it. For this initial version the endpoint accepts one document at a time and a question is needed, check this process on the diagram below:
+- `POST /resources/docs`
+- `POST /genai/search-in-documents`
+
+On `/resources/docs` the documents are uploaded to local system and then broke down into small chunks to be stored on a vector database.
+
+The `/genai/search-in-documents` endpoint uses RAG concept, it's responsible to create an Embedding of the user question, and retrieve the most relevant chunks from vector database using it as context for follow-up questions. Also, it uses Redis to store and retrieve chat history during user's session.
+
+Check this process on the diagram below:
 
 ![GenAI Search in Document Flow](docs/genai-flow.png 'GenAI Search in Document Flow')
 
@@ -128,3 +132,5 @@ Current supported roles are: [`admin`, `user`]:
 | GET status/                    | [x]   | [x]  |
 | POST /genai/translate          | [x]   | [x]  |
 | POST /genai/search-in-document | [x]   | [x]  |
+| GET /genai/chat-history        | [x]   | [x]  |
+| POST /resources/docs           | [x]   | [x]  |

docs/genai-flow.png

@@ -58,8 +58,13 @@ const router = express.Router()
  *                   items:
  *                     type: string
  *                   example: ["text field should not be empty"]
- *     security:
- *       - bearerAuth: []
+ *     parameters:
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  */
 router.post(
 	'/translate',
@@ -98,8 +103,13 @@ router.post(
  *                 data:
  *                   type: string
  *                   example: The project aims to develop and validate a web platform (software) for automatically correcting assessments created in Microsoft Word.
- *     security:
- *       - bearerAuth: []
+ *     parameters:
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  */
 router.post(
 	'/search-in-documents',
@@ -155,12 +165,6 @@ router.post(
  *                             example: {}
  *     parameters:
  *       - in: header
- *         name: Content-Type
- *         required: true
- *         schema:
- *           type: string
- *           example: application/json
- *       - in: header
  *         name: Authorization
  *         required: true
  *         schema:

src/modules/genai/application/routes/index.ts

@@ -72,12 +72,6 @@ const router = express.Router()
  *                         example: Please provide at least one file!
  *     parameters:
  *       - in: header
- *         name: Content-Type
- *         required: true
- *         schema:
- *           type: string
- *           example: application/json
- *       - in: header
  *         name: Authorization
  *         required: true
  *         schema:

src/modules/resources/application/routes/index.ts

@@ -46,8 +46,13 @@ const router = express.Router()
  *                       name:
  *                         type: string
  *                         example: User
- *     security:
- *       - bearerAuth: []
+ *     parameters:
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  */
 router.get('/', isAuthenticated, usersController.getUser)
 
@@ -63,6 +68,12 @@ router.get('/', isAuthenticated, usersController.getUser)
  *         required: true
  *         schema:
  *           type: string
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  *     requestBody:
  *       required: true
  *       content:
@@ -120,9 +131,7 @@ router.get('/', isAuthenticated, usersController.getUser)
  *                       type: array
  *                       items:
  *                         type: string
- *                       example: ["Invalid email address", "name field is required"]
- *     security:
- *       - bearerAuth: []
+ *                       example: ["Invalid email address", "name field is
  */
 router.patch(
 	'/',
@@ -143,6 +152,12 @@ router.patch(
  *         required: true
  *         schema:
  *           type: string
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  *     requestBody:
  *       required: true
  *       content:
@@ -203,8 +218,6 @@ router.patch(
  *                       items:
  *                         type: string
  *                         example: Role is required.
- *     security:
- *       - bearerAuth: []
  */
 router.patch(
 	'/change-role/:id',
@@ -251,14 +264,10 @@ router.patch(
  *                         type: string
  *                         format: date-time
  *                         example: 2024-09-30T21:04:18.656Z
- *     headers:
- *       Content-Type:
- *         description: The content type of the response
- *         schema:
- *           type: string
- *           example: application/json
- *       Authorization:
- *         description: Bearer token for authorization
+ *     parameters:
+ *       - in: header
+ *         name: Authorization
+ *         required: true
  *         schema:
  *           type: string
  *           example: Bearer <token>
@@ -282,6 +291,12 @@ router.get(
  *         required: true
  *         schema:
  *           type: string
+ *       - in: header
+ *         name: Authorization
+ *         required: true
+ *         schema:
+ *           type: string
+ *           example: Bearer <token>
  *     responses:
  *       200:
  *         description: Successfully deleted the user
@@ -314,8 +329,6 @@ router.get(
  *                       role:
  *                         type: string
  *                         example: user
- *     security:
- *       - bearerAuth: []
  */
 router.delete(
 	'/:id',