Add API reference and API deploy

.env

@@ -1,7 +1,9 @@
 PORT = 8080
 
 URL = /venecodollar
-API = v1.1.10
+API = v1.2.0
 API_VER_URL = /api/v1
 
+API_DOC = /api/doc
+
 BASE_URL = https://monitordolarvenezuela.com/

README-ES.md

@@ -210,6 +210,34 @@ type DollarAverageType = {
 }
 ```
 
+## Referencia API
+
+El paquete también está desplegado y funciona como API para aquellos usuarios que no quieran o no puedan incorporarlo a sus proyectos como dependencia. 
+
+Para acceder a la API deben utilizar la ruta https://venecodollar.vercel.app/api/v1.
+
+Asimismo, pueden acceder a la documentación hecha en swagger para el proyecto ubicada aquí [documentación de la API venecodollar](https://venecodollar.vercel.app/api/doc).
+
+#### Obtener todas las entidades
+
+```http
+  GET /api/v1/dollar
+```
+
+Este endpoint permite obtener todas las entidades de seguimiento del dólar con su respectivo nombre y fecha de última actualización, así como una media de todas las entidades activas (es decir, las que tienen un valor del dólar superior a cero).
+
+#### Obtener entidades por un nombre
+
+```http
+  GET /api/v1/dollar/entity?name=${name}
+```
+
+| Parámetro Tipo Descripción
+| :-------- | :------- | :----------------------------------------- |
+| `name` | `string` | **Required**. Nombre de las entidades a obtener.
+
+Este endpoint permite obtener todas las entidades de seguimiento del dólar por el nombre proporcionado en el parámetro de la ruta. Si el nombre proporcionado coincide con más de una entidad, el endpoint devuelve una media de los valores dados por las entidades y la información de cada una de estas entidades. Si el nombre proporcionado coincide sólo con una entidad, el endpoint devolverá la información sólo para esa entidad.
+
 ## Contribuciones
 
 Se aceptan pull requests. Para cambios mayores, por favor abra un issue primero para discutir lo que le gustaría cambiar.

README.md

@@ -210,6 +210,34 @@ type DollarAverageType = {
 }
 ```
 
+## API Reference
+
+The package is also deployed and works as an API for those users who do not want to or cannot incorporate it into their projects as a dependency. 
+
+To access the API they should use the path https://venecodollar.vercel.app/api/v1.
+
+Likewise, you can access the documentation made in swagger for the project located here [venecodollar API documentation](https://venecodollar.vercel.app/api/doc).
+
+#### Get all entities
+
+```http
+  GET /api/v1/dollar
+```
+
+This endpoint allows obtaining all the dollar monitoring entities with their respective name and last update date, as well as an average of all the active entities (i.e., those with a dollar value greater than zero).
+
+#### Get entities by name
+
+```http
+  GET /api/v1/dollar/entity?name=${name}
+```
+
+| Parameter | Type     | Description                                |
+| :-------- | :------- | :----------------------------------------- |
+| `name`      | `string` | **Required**. Name of entitites to fetch |
+
+This endpoint allows to obtain all the monitoring entities of the dollar by the name provided in the path parameter. If the name provided matches more than one entity, the endpoint returns an average of the values given by the entities and the information for each of these entities. If the name provided matches only one entity, the endpoint will return the information for that entity only.
+
 ## Contributing
 
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

build/index.js

@@ -3,22 +3,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// Dependencies
 var express_1 = __importDefault(require("express"));
 var cors_1 = __importDefault(require("cors"));
 var morgan_1 = __importDefault(require("morgan"));
 var routes_1 = __importDefault(require("./routes"));
+var swagger_1 = __importDefault(require("./services/swagger"));
+var swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+// Dotenv
 require('dotenv').config();
+// Settings
 var port = process.env.PORT || 3030;
 var app = (0, express_1.default)();
+// Middlewares
 app.use(express_1.default.json());
 app.use((0, morgan_1.default)('tiny'));
 app.use(express_1.default.urlencoded({ extended: false }));
 app.use((0, cors_1.default)());
-var url = "".concat(process.env.API_VER_URL);
-app.use(url, routes_1.default);
-app.get(url, function (_, res) { return res.send("Connected!"); });
+// Routes
+var URL = "".concat(process.env.API_VER_URL);
+var DOC_URL = "".concat(process.env.API_DOC);
+app.use(URL, routes_1.default);
+app.use(DOC_URL, swagger_ui_express_1.default.serve, swagger_ui_express_1.default.setup(swagger_1.default));
+// Start server
+app.get(URL, function (_, res) { return res.send("Connected!"); });
 app.listen(port, function () {
-    console.log("Server is running on ".concat(url));
+    console.log("Server is running on ".concat(URL));
 });
 /**
  * This module is responsible for setting up an Express server that listens for incoming requests.

build/routes/RDollar.js

@@ -3,15 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var router = require('express').Router();
 var CDollar_1 = require("../controllers/CDollar");
 /**
- * Express router for handling GET requests to the root endpoint.
- * @route GET /
- * @handler getDollar
+ * @swagger
+ * /api/v1/dollar:
+ *  get:
+ *    summary: Get the dollar values in terms of bolivars (Bs.) given by the monitoring entities and an average of the same.
+ *    tags:
+ *      - dollar
+ *    description: Get an object which contains the date on which the query was made, an average of all the dollar values given by the queried monitoring entities and an array with the monitored entities.
+ *    responses:
+ *      200:
+ *        description: The API request has been successful.
+ *      404:
+ *        description: Not found.
+ *      500:
+ *        description: Internal server error.
+ *
+ * /api/v1/dollar/entity?name={name}:
+ *  get:
+ *    summary: Get the dollar values in terms of bolivars (Bs.) given by the control entities filtered by name and, in the event that the name coincides with more than one entity, an average of the same.
+ *    tags:
+ *      - dollar
+ *    description: Gets an object containing the entities in charge of monitoring the dollar value filtered by name. In case the name matches more than one entity, the query date and an average of all displayed entities will be returned along with the data of those entities.
+ *    parameters:
+ *      - name: name
+ *        in: path
+ *        description: Name of entity to return
+ *        required: true
+ *        schema:
+ *          type: string
+ *          example: '@DolarToday'
+ *    responses:
+ *      200:
+ *        description: The API request has been successful.
+ *      404:
+ *        description: Not found.
+ *      500:
+ *        description: Internal server error.
  */
 router.get('/', CDollar_1.getDollar);
-/**
- * Express router for handling GET requests to the '/entity' endpoint.
- * @route GET /entity
- * @handler getSpecificDollar
- */
 router.get('/entity', CDollar_1.getSpecificDollar);
 module.exports = router;

build/routes/index.js

@@ -6,5 +6,5 @@ var router = require('express').Router();
  * @route /dolar
  * @handler require('./RDollar')
  */
-router.use('/dolar', require('./RDollar'));
+router.use('/dollar', require('./RDollar'));
 exports.default = router;

build/services/swagger.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var swagger_jsdoc_1 = __importDefault(require("swagger-jsdoc"));
+var swaggerOptions = {
+    openapi: '3.0.0',
+    definition: {
+        info: {
+            title: 'Venecodollar API Documentation',
+            version: '1.2.0',
+            description: "This section represents the Swagger documentation of the API designed with Venecodollar's NPM package. Here it is possible to test the endpoints provided by this API.\n\nIf you wish to make use of the NPM package in your javascript or typescript project, please [click here](https://www.npmjs.com/package/venecodollar), where you will be redirected to the official Venecodollar NPM package page.",
+            contact: {
+                name: 'the developer',
+                email: '[email protected]',
+            },
+            license: {
+                name: 'MIT',
+                url: 'https://github.com/gustavoerivero/venecodollar/blob/main/LICENSE'
+            },
+            schemes: ['http', 'https'],
+            servers: [{ url: 'https://venecodollar.vercel.app/api/v1' }],
+        }
+    },
+    apis: ["".concat(__dirname, "/routes/*.ts"), './build/routes/*.js']
+};
+exports.default = (0, swagger_jsdoc_1.default)(swaggerOptions);

nodemon.json

@@ -1,6 +1,6 @@
 {
   "watch": ["src"],
-  "ext": ".ts,.js,.json",
+  "ext": ".ts, .js, .json, .yml",
   "ignore": [],
   "exec": "npx ts-node ./src/index.ts"
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "venecodollar",
-  "version": "1.1.10",
+  "version": "1.2.0",
   "description": "Library to consult the different dollar values and their average in terms of bolivars.",
   "keywords": [
     "dollar",
@@ -37,6 +37,8 @@
     "@types/express": "^4.17.17",
     "@types/morgan": "^1.9.4",
     "@types/node": "^18.15.13",
+    "@types/swagger-jsdoc": "^6.0.1",
+    "@types/swagger-ui-express": "^4.1.3",
     "axios": "^1.3.6",
     "cheerio": "^1.0.0-rc.12",
     "cors": "^2.8.5",
@@ -46,6 +48,8 @@
     "morgan": "^1.10.0",
     "nodemon": "^2.0.22",
     "rimraf": "^5.0.0",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^4.6.2",
     "ts-node": "^10.9.1",
     "typescript": "^5.0.4"
   },

src/index.ts

@@ -1,27 +1,37 @@
+// Dependencies
 import express, { Response } from 'express'
 import cors from 'cors'
 import morgan from 'morgan'
 import routes from './routes'
+import swaggerDocs from './services/swagger'
+import swaggerUI from 'swagger-ui-express'
 
+// Dotenv
 require('dotenv').config()
 
+// Settings
 const port = process.env.PORT || 3030
 const app = express()
 
+// Middlewares
 app.use(express.json())
 app.use(morgan('tiny'))
 app.use(express.urlencoded({ extended: false }))
 
 app.use(cors())
 
-const url = `${process.env.API_VER_URL}`
+// Routes
+const URL = `${process.env.API_VER_URL}`
+const DOC_URL = `${process.env.API_DOC}`
 
-app.use(url, routes)
+app.use(URL, routes)
+app.use(DOC_URL, swaggerUI.serve, swaggerUI.setup(swaggerDocs))
 
-app.get(url, (_, res: Response) => res.send(`Connected!`))
+// Start server
+app.get(URL, (_, res: Response) => res.send(`Connected!`))
 
 app.listen(port, () => {
-  console.log(`Server is running on ${url}`)
+  console.log(`Server is running on ${URL}`)
 })
 
 /**

src/json.d.ts

@@ -2,3 +2,8 @@ declare module "*.json" {
   const value: any
   export default value
 }
+
+declare module "*.yml" {
+  const value: any
+  export default value
+}

src/routes/RDollar.ts

@@ -2,17 +2,44 @@ const router = require('express').Router()
 import { getDollar, getSpecificDollar } from '../controllers/CDollar'
 
 /**
- * Express router for handling GET requests to the root endpoint.
- * @route GET /
- * @handler getDollar
+ * @swagger
+ * /api/v1/dollar:
+ *  get:
+ *    summary: Get the dollar values in terms of bolivars (Bs.) given by the monitoring entities and an average of the same.
+ *    tags:
+ *      - dollar
+ *    description: Get an object which contains the date on which the query was made, an average of all the dollar values given by the queried monitoring entities and an array with the monitored entities.
+ *    responses:
+ *      200:
+ *        description: The API request has been successful.
+ *      404:
+ *        description: Not found.
+ *      500:
+ *        description: Internal server error.
+ * 
+ * /api/v1/dollar/entity?name={name}:
+ *  get:
+ *    summary: Get the dollar values in terms of bolivars (Bs.) given by the control entities filtered by name and, in the event that the name coincides with more than one entity, an average of the same.
+ *    tags:
+ *      - dollar
+ *    description: Gets an object containing the entities in charge of monitoring the dollar value filtered by name. In case the name matches more than one entity, the query date and an average of all displayed entities will be returned along with the data of those entities.
+ *    parameters:
+ *      - name: name
+ *        in: path
+ *        description: Name of entity to return
+ *        required: true
+ *        schema:
+ *          type: string
+ *          example: '@DolarToday'
+ *    responses:
+ *      200:
+ *        description: The API request has been successful.
+ *      404:
+ *        description: Not found.
+ *      500:
+ *        description: Internal server error.
  */
 router.get('/', getDollar)
-
-/**
- * Express router for handling GET requests to the '/entity' endpoint.
- * @route GET /entity
- * @handler getSpecificDollar
- */
 router.get('/entity', getSpecificDollar)
 
 module.exports = router

src/routes/index.ts

@@ -7,6 +7,6 @@ const router = require('express').Router()
  * @route /dolar
  * @handler require('./RDollar')
  */
-router.use('/dolar', require('./RDollar'))
+router.use('/dollar', require('./RDollar'))
 
 export default router

src/services/swagger.ts

@@ -0,0 +1,25 @@
+import swaggerJsonDoc from 'swagger-jsdoc'
+
+const swaggerOptions = {
+  openapi: '3.0.0',
+  definition: {
+    info: {
+      title: 'Venecodollar API Documentation',
+      version: '1.2.0',
+      description: "This section represents the Swagger documentation of the API designed with Venecodollar's NPM package. Here it is possible to test the endpoints provided by this API.\n\nIf you wish to make use of the NPM package in your javascript or typescript project, please [click here](https://www.npmjs.com/package/venecodollar), where you will be redirected to the official Venecodollar NPM package page.",
+      contact: {
+        name: 'the developer',
+        email: '[email protected]',
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://github.com/gustavoerivero/venecodollar/blob/main/LICENSE'
+      },
+      schemes: ['http', 'https'],
+    servers: [{ url: 'https://venecodollar.vercel.app/api/v1' }],
+    }
+  },
+  apis: [`${__dirname}/routes/*.ts`, './build/routes/*.js']
+}
+
+export default swaggerJsonDoc(swaggerOptions)