From 9aebd12d162fc72d36f5d1593597048a21b6c3a4 Mon Sep 17 00:00:00 2001 From: Patrick Mueller Date: Sun, 9 Jan 2022 20:32:44 +0100 Subject: [PATCH] Adding documentation for the rest of crr/ --- .../climbing_gyms/climbingGyms.router.ts | 3 + .../climbing_routes/climbingRoutes.router.ts | 146 ++++++++++++++++++ .../route_comments/routeComments.router.ts | 94 +++++++++++ .../route_ratings/routeRatings.router.ts | 80 ++++++++++ .../RaPlaMiddleware.router.ts | 7 +- 5 files changed, 329 insertions(+), 1 deletion(-) diff --git a/src/models/climbing-route-rating/climbing_gyms/climbingGyms.router.ts b/src/models/climbing-route-rating/climbing_gyms/climbingGyms.router.ts index fddd129..16bb5b6 100644 --- a/src/models/climbing-route-rating/climbing_gyms/climbingGyms.router.ts +++ b/src/models/climbing-route-rating/climbing_gyms/climbingGyms.router.ts @@ -99,18 +99,21 @@ climbingGymRouter.get('/', async (req: Request, res: Response) => { * description: The name of the gym * schema: * type: string + * example: DAV Kletterhalle * - in: query * name: city * required: true * description: The city where the gym is in * schema: * type: string + * example: Karlsruhe * - in: query * name: h-captcha-response * required: true * description: The hCaptcha response key * schema: * type: string + * example: P0_ey[...]bVu */ climbingGymRouter.post('/', async (req: Request, res: Response) => { try { diff --git a/src/models/climbing-route-rating/climbing_routes/climbingRoutes.router.ts b/src/models/climbing-route-rating/climbing_routes/climbingRoutes.router.ts index 17f0e3e..e792752 100644 --- a/src/models/climbing-route-rating/climbing_routes/climbingRoutes.router.ts +++ b/src/models/climbing-route-rating/climbing_routes/climbingRoutes.router.ts @@ -13,6 +13,47 @@ import {verifyCaptcha} from '../common/VerifyCaptcha'; */ export const climbingRoutesRouter = express.Router(); +/** + * @swagger + * /crr/routes: + * get: + * summary: Retrieve all known climbing routes + * description: Returns all climbing routes in a JSON list + * tags: + * - climbing-route-rating + * responses: + * 200: + * description: Success + * content: + * application/json: + * schema: + * type: array + * items: + * type: object + * properties: + * route_id: + * type: string + * description: The route id + * example: duck-score-guide + * gym_id: + * type: integer + * description: The id of the gym that the route belongs to + * example: 1 + * name: + * type: string + * description: The route name + * example: Mary Poppins + * difficulty: + * type: string + * description: The difficulty of the route + * example: 'DE: 5, FR: 5c' + * route_setting_date: + * type: datetime + * description: The route setting date + * example: 2022-01-07T23:00:00.000Z + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + */ climbingRoutesRouter.get('/', async (req: Request, res: Response) => { try { const routes: ClimbingRoute[] = await RouteService.findAll(); @@ -29,6 +70,55 @@ climbingRoutesRouter.get('/', async (req: Request, res: Response) => { } }); +/** + * @swagger + * /crr/routes/{id}: + * get: + * summary: Retrieve the route with the given id + * description: Returns the climbing route with the given id if it exists + * tags: + * - climbing-route-rating + * responses: + * 200: + * description: Success + * content: + * application/json: + * schema: + * type: array + * items: + * type: object + * properties: + * route_id: + * type: string + * description: The route id + * example: duck-score-guide + * gym_id: + * type: integer + * description: The id of the gym that the route belongs to + * example: 1 + * name: + * type: string + * description: The route name + * example: Mary Poppins + * difficulty: + * type: string + * description: The difficulty of the route + * example: 'DE: 5, FR: 5c' + * route_setting_date: + * type: datetime + * description: The route setting date + * example: 2022-01-07T23:00:00.000Z + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: path + * name: id + * required: true + * description: The id of the route + * schema: + * type: string + * example: duck-score-guide + */ climbingRoutesRouter.get('/:id', async (req: Request, res: Response) => { try { let route_id = req.params.id; @@ -47,6 +137,62 @@ climbingRoutesRouter.get('/:id', async (req: Request, res: Response) => { } }); +/** + * @swagger + * /crr/routes: + * post: + * summary: Create a new climbing route + * description: Creates a new climbing route and returns the id of the created route + * tags: + * - climbing-route-rating + * responses: + * 201: + * description: Created + * content: + * application/json: + * schema: + * type: object + * properties: + * route_id: + * type: string + * description: The route id + * example: duck-score-guide + * 400: + * description: Wrong parameters, see response body for detailed information + * 403: + * description: Invalid captcha, please try again. + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: query + * name: gym_id + * required: true + * description: The gym id of the gym that the route belongs to + * schema: + * type: integer + * example: 1 + * - in: query + * name: name + * required: true + * description: The name of the route + * schema: + * type: string + * example: Mary Poppins + * - in: query + * name: difficulty + * required: true + * description: The difficulty of the route + * schema: + * type: string + * example: 'DE: 5, FR: 5c' + * - in: query + * name: h-captcha-response + * required: true + * description: The hCaptcha response key + * schema: + * type: string + * example: P0_ey[...]bVu + */ climbingRoutesRouter.post('/', async (req: Request, res: Response) => { try { let gym_id = Number(req.query.gym_id); diff --git a/src/models/climbing-route-rating/route_comments/routeComments.router.ts b/src/models/climbing-route-rating/route_comments/routeComments.router.ts index 8d34beb..f3c8316 100644 --- a/src/models/climbing-route-rating/route_comments/routeComments.router.ts +++ b/src/models/climbing-route-rating/route_comments/routeComments.router.ts @@ -7,6 +7,51 @@ import {verifyCaptcha} from '../common/VerifyCaptcha'; export const routeCommentsRouter = express.Router(); +/** + * @swagger + * /crr/comments/by/route/{id}: + * get: + * summary: Retrieve the comments for the given route + * description: Returns all comments for the route with the specified id + * tags: + * - climbing-route-rating + * responses: + * 200: + * description: Success + * content: + * application/json: + * schema: + * type: array + * items: + * type: object + * properties: + * comment_id: + * type: integer + * description: The comment id + * example: 2 + * route_id: + * type: string + * description: The id of the route that the comment belongs to + * example: duck-score-guide + * comment: + * type: string + * description: The comment text + * example: Nice route! Was a lot of fun! + * timestamp: + * type: datetime + * description: The time when the comment was sent + * example: 2022-01-08T21:43:31.000Z + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: path + * name: id + * required: true + * description: The id of the route + * schema: + * type: string + * example: duck-score-guide + */ routeCommentsRouter.get('/by/route/:id', async (req: Request, res: Response) => { try { let route_id = req.params.id; @@ -25,6 +70,55 @@ routeCommentsRouter.get('/by/route/:id', async (req: Request, res: Response) => } }); +/** + * @swagger + * /crr/comments: + * post: + * summary: Create a new comment + * description: Creates a new comment and returns the id of the created comment + * tags: + * - climbing-route-rating + * responses: + * 201: + * description: Created + * content: + * application/json: + * schema: + * type: object + * properties: + * comment_id: + * type: integer + * description: The comment id + * example: 1 + * 400: + * description: Wrong parameters, see response body for detailed information + * 403: + * description: Invalid captcha, please try again. + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: query + * name: route_id + * required: true + * description: The id of the route to create the comment for + * schema: + * type: string + * example: duck-score-guide + * - in: query + * name: comment + * required: true + * description: The comment text + * schema: + * type: string + * example: Nice route! Was a lot of fun! + * - in: query + * name: h-captcha-response + * required: true + * description: The hCaptcha response key + * schema: + * type: string + * example: P0_ey[...]bVu + */ routeCommentsRouter.post('/', async (req: Request, res: Response) => { try { let route_id = req.query.route_id as string; diff --git a/src/models/climbing-route-rating/route_ratings/routeRatings.router.ts b/src/models/climbing-route-rating/route_ratings/routeRatings.router.ts index 1d8235f..36d28ba 100644 --- a/src/models/climbing-route-rating/route_ratings/routeRatings.router.ts +++ b/src/models/climbing-route-rating/route_ratings/routeRatings.router.ts @@ -6,6 +6,37 @@ import {verifyCaptcha} from '../common/VerifyCaptcha'; export const routeRatingsRouter = express.Router(); +/** + * @swagger + * /crr/ratings/by/route/{id}: + * get: + * summary: Retrieve the rating for the given route + * description: Returns the medium amount of stars that the route got + * tags: + * - climbing-route-rating + * responses: + * 200: + * description: Success + * content: + * application/json: + * schema: + * type: object + * properties: + * rating: + * type: float + * description: The median amount of stars + * example: 4.5 + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: path + * name: id + * required: true + * description: The id of the route + * schema: + * type: string + * example: duck-score-guide + */ routeRatingsRouter.get('/by/route/:id', async (req: Request, res: Response) => { try { let route_id = req.params.id; @@ -24,6 +55,55 @@ routeRatingsRouter.get('/by/route/:id', async (req: Request, res: Response) => { } }); +/** + * @swagger + * /crr/ratings: + * post: + * summary: Create a new rating + * description: Creates a new rating and returns the id of the created rating + * tags: + * - climbing-route-rating + * responses: + * 201: + * description: Created + * content: + * application/json: + * schema: + * type: object + * properties: + * rating_id: + * type: integer + * description: The rating id + * example: 1 + * 400: + * description: Wrong parameters, see response body for detailed information + * 403: + * description: Invalid captcha, please try again. + * 500: + * description: A server error occurred. Please try again. If this issue persists, contact the admin. + * parameters: + * - in: query + * name: route_id + * required: true + * description: The id of the route to create the rating for + * schema: + * type: string + * example: duck-score-guide + * - in: query + * name: stars + * required: true + * description: The amount of stars to give + * schema: + * type: integer + * example: 4 + * - in: query + * name: h-captcha-response + * required: true + * description: The hCaptcha response key + * schema: + * type: string + * example: P0_ey[...]bVu + */ routeRatingsRouter.post('/', async (req: Request, res: Response) => { try { let route_id = req.query.route_id as string; diff --git a/src/models/rapla-middleware/RaPlaMiddleware.router.ts b/src/models/rapla-middleware/RaPlaMiddleware.router.ts index 3e9cea4..0b124b5 100644 --- a/src/models/rapla-middleware/RaPlaMiddleware.router.ts +++ b/src/models/rapla-middleware/RaPlaMiddleware.router.ts @@ -34,30 +34,35 @@ export const raPlaMiddlewareRouter = express.Router(); * description: The user from RaPla, can be taken directly from the RaPla link * schema: * type: string + * example: mueller * - in: query * name: file * required: true * description: The file from RaPla, can be taken directly from the RaPla link * schema: * type: string + * example: TINF19B4 * - in: query * name: blockers * required: false * description: Whether to remove blockers from the .ics file * schema: - * type: boolean [0,1] + * type: boolean + * example: 1 * - in: query * name: wahl * required: false * description: The chosen elective module which is not to be filtered out * schema: * type: integer + * example: 0 * - in: query * name: pflicht * required: false * description: The chosen profile module which is not to be filtered out * schema: * type: integer + * example: 2 */ raPlaMiddlewareRouter.get('/', async (req: Request, res: Response) => { try {