API Calculadora usando o express + swaggerUi

Vamos aprender a usar o swaggerUi, para termos uma interface simples mas funcional para as nossas API’s, vamos também neste tutorial utilizar o nodemon, quando usamos o nodemon cada vez que alteramos alguma coisa no nosso projeto o servidor é recarregado e assim não temos que ser nós a fechar o servidor e voltar a ativa-lo, o que nos vai poupar bastante tempo. Normalmente quando se usa o swagger costuma-se colocar todo o código da API no mesmo ficheiro, nós vamos continuar a usar a estrutura Model, View, Controller, neste caso a view da nossa API vai ser um ficheiro swagger.json, onde definimos a User Interface da nossa API.

Vamos começar por criar a pasta do nosso projeto ao qual podemos chamar calculadoraSwagger, depois na linha de comandos vamos dar inicio ao nosso projeto com o comando

npm init 

Onde vamos definir os dados da nossa API que ficaram guardados no ficheiro package.json, como podemos ver na figura seguinte

Acrescentamos uma virgula depois de fechar aspas na linha 7 e acrescentamos a linha que está assinalada para definir um alias para quando usamos o nodemon, e assim para ativarmos o servidor com o nodemon executamos o seguinte comando

npm run inicio

Depois instalamos as dependências necessárias, para o nosso projeto, executando o seguinte código

npm install express nodemon swagger-ui-express --save

Depois vamos criar o ficheiro index.js

onde vamos inserir o seguinte código

//Framework express.js
const express = require('express');
// to serve auto-generated swagger-ui generated API docs from express
const swaggerUi = require('swagger-ui-express');
swaggerDocument = require('./swagger.json');
// Máquina e Porto Lógico
const host = 'localhost';
const porto = 8081;
const routes = require("./routes/calculadora.route");
//iniciar app express
const app = express();
app.use(
'/api',
swaggerUi.serve,
swaggerUi.setup(swaggerDocument)
);
app.use("/",routes);
app.use(express.json());
// Iniciar servidor
app.listen(porto, () => {
console.log('Servidor a executar no porto ' + porto);
});

E o ficheiro ficará assim

Depois, para organizarmos o nosso projeto, vamos criar as seguintes pastas

e podemos faze-lo através da CMD

mkdir views controllers routes

Neste exemplo não precisamos da pasta models, porque como não estamos a guardar nada numa base de dados, não precisamos definir como a informação é guardada

De seguida criamos um ficheiro calculadora.controller.js dentro da pasta controllers, onde vamos colocar as funções da nossa calculadora, inserido o seguinte código

exports.soma = function (req, res) {
const c = parseInt(req.params.a) + parseInt(req.params.b);
//console.log('gg',req.params.a , req.params.b , c)
res.send(c.toString());
};
exports.subtracao = function (req, res){
const c = parseInt(req.params.a) - parseInt(req.params.b);
console.log(req.params.a , req.params.b , c)
res.send(c.toString());
}
exports.multiplicacao = function (req, res) {
const c = parseInt(req.params.a) * parseInt(req.params.b);
//console.log(req.params.a , req.params.b , c)
res.send(c.toString());
}
exports.divisao = function (req, res) {
const c = parseInt(req.params.a) / parseInt(req.params.b);
//console.log(req.params.a , req.params.b , c)
res.send(c.toString());
}

E o ficheiro ficará assim

Depois passamos a pasta routes onde vamos criar o ficheiro calculadora.route.js, onde vamos colocar as routes (caminhos), para as funções que criamos no ficheiro calculadora.controller.js.

Para definir as routes vamos inserir o seguinte código no ficheiro calculadora.route.js

const express = require("express");
const router = express.Router();
//invocar o controller
const calculadora_controller = require('../controllers/calculadora.controller');
//route soma
router.route("/soma/:a&:b").get(calculadora_controller.soma);
//route subtracao
router.route("/subtracao/:a&:b").get(calculadora_controller.subtracao);
//route multiplicacao
router.route("/multiplicacao/:a&:b").get(calculadora_controller.multiplicacao);
//route divisao
router.route("/divisao/:a&:b").get(calculadora_controller.divisao);
module.exports = router;

E o ficheiro ficará assim

Depois vamos a pasta views onde vamos em json, definir aUI da nossa API, usando o swagger, vamos então criar o ficheiro swagger.json, e vamos inserir o seguinte código

{
"swagger": "2.0",
"info": {
"title": "Calculadora",
"description": "API Calculadora swagger",
"version": "1.0"
},
"host": "localhost:8081",
"basePath": "/",
"schemes": [
"http"
],
"paths": {
"/soma/{a}&{b}": {
"get": {
"description": "Responds with a sum of two numbers.",
"operationId": "Add two integers",
"parameters": [
{
"name": "a",
"in": "path",
"description": "First operand. Default value is <code>51</code>.",
"required": true,
"default": "51"
},
{
"name": "b",
"in": "path",
"description": "Second operand. Default value is <code>49</code>.",
"required": true,
"default": "49",
"enum": [
"49",
"50"
]
}
],
"responses": { }
}
},
"/subtracao/{a}&{b}": {
"get": {
"description": "Responds with a difference between two numbers.",
"operationId": "Subtract two integers",
"parameters": [
{
"name": "a",
"in": "path",
"description": "First operand. Default value is <code>100</code>.",
"required": true,
"default": "100",
"enum": [
"100"
]
},
{
"name": "b",
"in": "path",
"description": "Second operand. Default value is <code>50</code>.",
"required": true,
"default": "50",
"enum": [
"50"
]
}
],
"responses": {}
}
},
"/divisao/{a}&{b}": {
"get": {
"description": "Responds with a quotient of two numbers.",
"operationId": "Divide two integers",
"parameters": [
{
"name": "a",
"in": "path",
"description": "First operand. Default value is <code>100</code>.",
"required": true,
"default": "100",
"enum": [
"100"
]
},
{
"name": "b",
"in": "path",
"description": "Second operand. Default value is <code>20</code>.",
"required": true,
"default": "20",
"enum": [
"20"
]
}
],
"responses": {}
}
},
"/multiplicacao/{a}&{b}": {
"get": {
"description": "Responds with a product of two numbers.",
"operationId": "Multiply two integers",
"parameters": [
{
"name": "a",
"in": "path",
"description": "First operand. Default value is <code>20</code>.",
"required": true,
"default": "20",
"enum": [
"20"
]
},
{
"name": "b",
"in": "path",
"description": "Second operand. Default value is <code>5</code>.",
"required": true,
"default": "5",
"enum": [
"5"
]
}
],
"responses": {}
}
}
}
}

E o ficheiro ficará assim

Agora vamos correr o servidor com o nodemon usando o seguinte comando

npm run inicio

Na CMD do VSCode deverá aparecer o seguinte

Agora vamos ao browser e inserir o seguinte url

http://localhost:8081/api

E o resultado será a UI que criamos com o swagger

Podemos agora testar as funções para ver que realmente estão a funcionar

A soma

A subtração

A divisão

E a multiplicação

E assim criamos uma calculadora muito simples mas com uma UI bastante simples e funcional.

Este projeto está disponivel no repositório do github.