add jsdoc plugin

Express/barAndCafe/jsdoc.json

@@ -6,10 +6,15 @@
         "allowUnknownTags": true
     },
     "plugins": [
-        "node_modules/better-docs/typescript"
+        "node_modules/better-docs/typescript",
+        "plugins/markdown",
+        "jsdoc-mermaid"
     ],
     "source": {
         "include": ["./src"],
         "includePattern": "\\.(jsx|js|ts|tsx)$"
+    },
+    "templates": {
+        "search": true
     }
-}
+}

Express/barAndCafe/package-lock.json

@@ -23,6 +23,7 @@
         "better-docs": "^2.7.3",
         "jest": "^29.7.0",
         "jsdoc": "^4.0.3",
+        "jsdoc-mermaid": "^1.0.0",
         "nodemon": "^3.1.0",
         "rewire": "^7.0.0",
         "superagent": "^9.0.2",
@@ -8512,6 +8513,27 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/jsdoc-mermaid": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/jsdoc-mermaid/-/jsdoc-mermaid-1.0.0.tgz",
+      "integrity": "sha512-WgXR/E1369RurPVFkyNzUWP5wB5xQkm0p+vdIh/cX6ZtEQBb5KdeukDje47Du++IehwztkR3GJcwYhM+eaq/4w==",
+      "dev": true,
+      "dependencies": {
+        "doctrine": "^2.0.0"
+      }
+    },
+    "node_modules/jsdoc-mermaid/node_modules/doctrine": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz",
+      "integrity": "sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==",
+      "dev": true,
+      "dependencies": {
+        "esutils": "^2.0.2"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/jsdoc/node_modules/escape-string-regexp": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",

Express/barAndCafe/package.json

@@ -29,6 +29,7 @@
     "better-docs": "^2.7.3",
     "jest": "^29.7.0",
     "jsdoc": "^4.0.3",
+    "jsdoc-mermaid": "^1.0.0",
     "nodemon": "^3.1.0",
     "rewire": "^7.0.0",
     "superagent": "^9.0.2",

Express/barAndCafe/src/app.ts

@@ -55,7 +55,40 @@ app.get("/welcome", getWelcome)
 app.get("/otm/city", getCity)
 
 
-//XXX: faire la doc SWAGGER
+/**
+ * @openapi
+ * /otm/radius:
+ *  get:
+ *      summary: return the drinks in a radius
+ *      description: return the drinks in a defined radius
+ *      parameters:
+ *        - name: lon
+ *          in: query
+ *          required: true
+ *          description: longitude of the center of the radius
+ *          schema:
+ *              type: number
+ *              minimum: -180
+ *              maximum: 180
+ *        - name: lat
+ *          in: query
+ *          required: true
+ *          description: latitude of the center of the radius
+ *          schema:
+ *              type: number
+ *              minimum: -90
+ *              maximum: 90
+ *        - name: radius
+ *          in: query
+ *          description: size of the radius
+ *      responses:
+ *          200:
+ *              description: Return a list of bars and coffee in city in geoJSON format
+ *          400:
+ *              description: Missing Argument Error
+ *          401:
+ *              description: Missing OTM tocken
+ */
 app.get("/otm/radius", getRadius)
 
 export default app

Express/barAndCafe/src/openTripMaps.ts

@@ -3,9 +3,15 @@ import express from "express"
 import * as dotenv from "dotenv";
 
 dotenv.config({path: '../../.env'})
-
 const key = process.env.OPEN_TRIP_MAPS_KEY
 
+/**
+ * make GET request to the OTM for radius search.
+ * @param {string} lon Longitude of radius center point
+ * @param {string} lat Latitude du point central du rayon
+ * @param {string} radius search radius size in meters
+ * @returns {FeatureCollection} a list of POIs with their type, id, etc. (cf: [opentripmap](https://dev.opentripmap.org/docs#))
+ */
 async function callRadius(lon: string, lat: string, radius = '1000') {
     const optionsDrink = {
         method: 'GET',
@@ -28,7 +34,11 @@ async function callRadius(lon: string, lat: string, radius = '1000') {
     }
 }
 
-
+/**
+ * make GET request to the OTM for city info.
+ * @param {string} name Name of a city
+ * @returns {Geoname} info of a search city their name, country, lat, lon, etc. (cf: [opentripmap](https://dev.opentripmap.org/docs#))
+ */
 async function callCity(name:string) {
     const optionsCity = {
         method: 'GET',
@@ -70,7 +80,7 @@ export async function getCity(req: express.Request, res: express.Response) {
 }
 
 /**
- * Handle GET request for city search route ('/otm/radius').
+ * Handle GET request for radius search route ('/otm/radius').
  * @param {express.Request} req - HTTP Request object.
  * @param {express.Response} res - HTTP Response object.
  */