DAWM

Guía 16

DAWM / Proyecto04

Actividades previas

Actividades en clases

REST API

  1. Clone localmente tu repositorio restapi.

  2. Desde la línea de comandos, dentro del proyecto instale los módulos swagger-autogen y swagger-ui-express

     npm install swagger-autogen swagger-ui-express

  3. En la raíz del proyecto, cree el archivo de configuración de ./swagger.js con el siguiente contenido:

     const swaggerAutogen = require('swagger-autogen')()

 const doc = {
   "info": {
     "title": 'REST API',
     "description": 'REST API with Express and Firestore'
   },
   "host": 'localhost:5000',
   "basePath": "/api",
 };

 const outputFile = './swagger_output.json'
 const endpointsFiles = ['./routes/*.js']

 swaggerAutogen(outputFile, endpointsFiles, doc)

  4. Modifique el controlador ./controllers/itemControllers.js con la descripción de cada función.

     ...
    
 exports.getItem = async (req, res) => {

   /* 
     #swagger.tags = ['Items']
     #swagger.description = 'Get an item entry'
     #swagger.summary = 'Get an item entry'
     #swagger.parameters['id'] = {
         description: 'Item id',
         required: true,
     }
     #swagger.responses[404] = {
         description: 'Item not found',
     }
     #swagger.responses[400] = {
         description: 'Bad request',
     }
     #swagger.responses[200] = {
         description: 'Get an item by id',
     }
   */
   ...
 }

 exports.getAllItems = async (req, res) => {

   /* 
     #swagger.tags = ['Items']
     #swagger.description = 'Get all items entries'
     #swagger.summary = 'Get all items entries'
     #swagger.responses[200] = {
         description: 'Items entries successfully obtained',
     }
     #swagger.responses[400] = {
         description: 'Bad request',
     }
   */
   ...
 }

 exports.createItem = async (req, res) => {

   /* 
     #swagger.tags = ['Items']
     #swagger.description = 'Create an item'
     #swagger.summary = 'Create an item'
     #swagger.parameters['data'] = {
         in: 'body',
         description: 'Data to create an item',
         required: true,
     }
     #swagger.responses[201] = {
         description: 'Item successfully created',
     }
     #swagger.responses[400] = {
         description: 'Bad request',
     }
   */
   ...
 }

 ...

  5. Modifique el archivo package.json y agregue la entrada swagger.

     ...
 "scripts": {
   ...
   "swagger": "node ./swagger.js"
   ...
 },
 ...

  6. Desde la línea de comandos, genere el archivo de configuración (./swagger_output.json) de Swagger, con el comando:

     npm run swagger

  7. Modifique el archivo con el servidor server.js con la referencia al módulo swagger-ui-express y al archivo generado swagger_output.json. Además, agregue la ruta a la documentación.

     const admin = require('firebase-admin');
 ...
 /* Referencia al módulo swagger-ui-express */
 const swaggerUi = require('swagger-ui-express')

 /* Referencia al archivo con la descripción */
 const swaggerFile = require('./swagger_output.json')
 ...

 const app = express();

 ...

 /* Ruta Base -> Documentación */
 app.use('/documentation', swaggerUi.serve, swaggerUi.setup(swaggerFile))

 app.use('/api', require('./routes/api'));

 ...

  8. Ejecute el servidor, con:

     npm start

  9. (STOP 1) Compruebe los endpoints de la documentación http://localhost:5000/documentation

Swagger output

  1. Versiona local y remotamente el repositorio restapi.

Postman

  1. Accede Postman o abre la aplicación e ingresa a tu cuenta.
  2. Accede a tu workspace con el nombre DAWM.

  3. Crea una colección desde la plantilla.

  4. Acceda a la colección y a la opción Variables.
    • Modifique la variable base_url con la URL de su REST API.
    • Guarde los cambios.

  5. (STOP 2) Modifique el URL del requerimiento Get data. Realice el requerimiento.

Actividad en grupo

En grupos de tres (3) personas, completen las siguientes tareas. Pueden utilizar la documentación oficial o un LLM.

  1. Complete la documentación para los métodos updateItem y deleteItem.

    Haga click aquí para ver la solución
     
    
     ...
     exports.updateItem = async (req, res) => {

       /* 
           #swagger.tags = ['Items']
           #swagger.description = ''
           #swagger.summary = ''
           #swagger.parameters['id'] = {
               description: '',
               required: true,
           }
           #swagger.parameters['data'] = {
               in: 'body',
               description: '',
               required: true,
           }
           #swagger.responses[200] = {
               description: '',
           }
           #swagger.responses[400] = {
               description: '',
           }
       */

       ...
     };

     exports.deleteItem = async (req, res) => {

       /* 
         #swagger.tags = ['Items']
         #swagger.description = ''
         #swagger.summary = ''
         #swagger.parameters['id'] = {
             description: '',
             required: true,
         }

         #swagger.responses[200] = {
             description: '',
         }
         #swagger.responses[400] = {
             description: '',
         }
       */
         ...
     }

     ...
  2. Desde la línea de comandos, genere el archivo de configuración (./swagger_output.json) de Swagger
  3. Ejecute el servidor.

  4. Compruebe los endpoints de la documentación http://localhost:5000/documentation

  5. Modifique el URL de requerimientos POST, PUT y DELETE en Postman. En los requerimientos con datos en el cuerpo del mensaje HTTTP, acceda a la opción Body > raw y escriba el objeto JSON a enviar.

     /* POST */

 {
     "name": "Molecule Man",
     "age": 29,
     "secretIdentity": "Dan Jukes",
     "powers": [
         "Radiation resistance",
         "Turning tiny",
         "Radiation blast"
     ]
 }

     /* PUT */

 {
     "name": "Ant Man",
     "age": 46,
     "secretIdentity": "Scott Lang",
     "powers": [
         "Genius-level intellect",
         "Size-shifting from nearly microscopic to ~100 feet gigantic (both at extremes)"
     ]
 }
    Haga click aquí para ver la solución

    POST

    PUT

    DELETE

  6. Compruebe con Postman los requerimientos y su resultado.
  7. (STOP 3) Versiona local y remotamente el repositorio restapi.

Documentación

Fundamental

Términos

swagger, documentación

Referencias