adolforeyna/EMI-Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add Swagger API documentation

Browse Source 
This commit introduces Swagger API documentation for all endpoints in the
application.

- Installs  and .
- Configures Swagger in  to generate and serve API documentation
  at .
- Adds JSDoc-style Swagger annotations to all routes in  and
  the  directory (, , ,
  , , ).
- Defines a cookie-based security scheme for authenticated routes.

This allows for interactive API documentation and testing via the
endpoint.
This commit is contained in:
Adolfo Reyna
2025-07-17 09:52:37 -04:00
parent 0a48327e93
commit 148ed696b2
9 changed files with 1891 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
routes/profile.js
View File

@@ -14,6 +14,36 @@ DB.getDB.then((DB) => {
return profile.userid === String(userid);
}
/**
* @swagger
* tags:
* name: Profiles
* description: User profile management
*/
/**
* @swagger
* /user/mine:
* get:
* summary: Get all profiles for the logged-in user
* tags: [Profiles]
* security:
* - cookieAuth: []
* responses:
* 200:
* description: OK
* content:
* application/json:
* schema:
* type: object
* properties:
* status:
* type: string
* profiles:
* type: array
* items:
* type: object
*/
router.get("/mine", async (req, res) => {
let userid = getUserId(req);
let profiles = await DB.getUserProfiles(userid);
@@ -23,6 +53,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/new:
* get:
* summary: (DEPRECATED) Create a new profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: query
* name: content
* required: true
* schema:
* type: object
* responses:
* 200:
* description: OK
*/
router.get("/new", async (req, res) => { //Deprecated please use route post("/")
let profile = {
userid: getUserId(req),
@@ -36,6 +84,27 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user:
* post:
* summary: Create a new profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* content:
* type: object
* responses:
* 200:
* description: OK
*/
router.post("/", async (req, res) => {
let profile = {
userid: getUserId(req),
@@ -57,6 +126,32 @@ DB.getDB.then((DB) => {
});
/**
* @swagger
* /user/invite:
* post:
* summary: Invite a new user by email
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* email:
* type: string
* format: email
* responses:
* 200:
* description: OK
* 400:
* description: Bad request
*/
router.post("/invite", async (req, res) => {
try {
const userid = getUserId(req);
@@ -94,6 +189,25 @@ DB.getDB.then((DB) => {
}
});
/**
* @swagger
* /user/invite/{email}:
* get:
* summary: Get invitation details for an email
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: email
* required: true
* schema:
* type: string
* format: email
* responses:
* 200:
* description: OK
*/
router.get("/invite/:email", async (req, res) => {
const userid = getUserId(req);
const email = req.params.email;
@@ -106,6 +220,18 @@ DB.getDB.then((DB) => {
return res.json({ status: "ok", ...r });
});
/**
* @swagger
* /user/groups:
* get:
* summary: Get a list of all groups
* tags: [Profiles]
* security:
* - cookieAuth: []
* responses:
* 200:
* description: OK
*/
router.get("/groups", async (req, res) => {
let groups = await DB.getGroups();
return res.json({
@@ -114,6 +240,18 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/following:
* get:
* summary: Get a list of groups the current profile is following
* tags: [Profiles]
* security:
* - cookieAuth: []
* responses:
* 200:
* description: OK
*/
router.get("/groups/following", async (req, res) => {
const profileId = getProfileId(req);
let groups = await DB.getFollowingGroups(profileId);
@@ -123,6 +261,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups:
* post:
* summary: Create a new group
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* responses:
* 200:
* description: OK
*/
router.post("/groups", async (req, res) => {
let profile = {
userid: getUserId(req),
@@ -137,6 +293,18 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/courses:
* get:
* summary: Get a list of all courses
* tags: [Profiles]
* security:
* - cookieAuth: []
* responses:
* 200:
* description: OK
*/
router.get("/courses", async (req, res) => {
let groups = await DB.getCourses();
return res.json({
@@ -145,6 +313,29 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/accept:
* post:
* summary: Accept a request to join a private group
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* groupid:
* type: string
* profileid:
* type: string
* responses:
* 200:
* description: OK
*/
router.post("/groups/accept", async (req, res) => {
//This function should be called to accept the join request
//of an user that attempt to join a private group.
@@ -164,6 +355,29 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/reject:
* post:
* summary: Reject a request to join a private group
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* groupid:
* type: string
* profileid:
* type: string
* responses:
* 200:
* description: OK
*/
router.post("/groups/reject", async (req, res) => {
//This function should be called to reject the join request
//of an user that attempt to join a private group.
@@ -183,6 +397,28 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/search:
* get:
* summary: Search for groups
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: query
* name: query
* required: true
* schema:
* type: string
* - in: query
* name: courses
* schema:
* type: boolean
* responses:
* 200:
* description: OK
*/
router.get("/groups/search", async (req, res) => {
let query = req.query.query;
let coursesB = req.query.courses ? true : false;
@@ -193,6 +429,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/{id}:
* get:
* summary: Get details for a specific group
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/groups/:id", async (req, res) => {
const groupid = req.params.id;
let groups = await DB.getGroup(groupid);
@@ -202,6 +456,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/{id}/subscribe:
* get:
* summary: Subscribe to a group
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/groups/:id/subscribe", async (req, res) => {
const groupid = req.params.id;
const profileid = getProfileId(req);
@@ -214,6 +486,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/groups/{id}/unsubscribe:
* get:
* summary: Unsubscribe from a group
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/groups/:id/unsubscribe", async (req, res) => {
const groupid = req.params.id;
const profileid = getProfileId(req);
@@ -224,6 +514,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/search:
* get:
* summary: Search for profiles
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: query
* name: query
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/search", async (req, res) => {
let query = req.query.query;
let profiles = await DB.searchProfile(query);
@@ -233,6 +541,29 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/setData:
* post:
* summary: Set custom data for a profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* key:
* type: string
* value:
* type: object
* responses:
* 200:
* description: OK
*/
router.post("/setData", (req, res) => {
const key = req.body.key;
const value = req.body.value;
@@ -243,6 +574,29 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/myProfile:
* post:
* summary: Update the current user's profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* profile:
* type: object
* data:
* type: object
* responses:
* 200:
* description: OK
*/
router.post("/myProfile", async (req, res) => {
let profile = {
userid: getUserId(req),
@@ -256,6 +610,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/{id}:
* get:
* summary: Get a specific profile by ID
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/:id", async (req, res) => {
let profileId = req.params.id;
let profile = await DB.getProfile(profileId);
@@ -265,6 +637,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/{id}:
* delete:
* summary: Delete a profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.delete("/:id", async (req, res) => {
const profileId = req.params.id;
const userid = getUserId(req);
@@ -278,6 +668,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/{id}/follow:
* get:
* summary: Follow a profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/:id/follow", async (req, res) => {
let followProfileId = req.params.id;
const profileid = getProfileId(req);
@@ -288,6 +696,24 @@ DB.getDB.then((DB) => {
});
});
/**
* @swagger
* /user/{id}/unfollow:
* get:
* summary: Unfollow a profile
* tags: [Profiles]
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: string
* responses:
* 200:
* description: OK
*/
router.get("/:id/unfollow", async (req, res) => {
let followProfileId = req.params.id;
const profileid = getProfileId(req);