Instalar y configurar Swagger para documentación en de una API en node con JavaScript

SwaggerConfigNodeJS.md

Congiguración de documentación automática son Swagger en NodeJS y Express

Explicación paso a paso, de como instalar y configurar swagger para documentación automática en un back-en realizado con NodeJS y JavaScript.

Instalación:

npm install swagger-jsdoc swagger-ui-express
npm install --save-dev swagger-autogen

Congiguración

• Creamos en la raíz del proyecto una carpeta "./swagger" esto es unicamente para que quede organizado. Dentro de esta carpeta creamos los archivos:
  • swagger_output.json
  • swagger.json
• Archivo swagger.js

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

const doc = {
    info: {
      title: 'Api para conectar con la Api de Github',
      description: 'Api para conectar con la Api de Github',
    },
    host: 'localhost:3000',
    schemes: ['http'],
  };

const outputFile = './swagger/swagger_output.json'
const endpointsFiles = ['./endpoints.js']

swaggerAutogen(outputFile, endpointsFiles, doc)

• En este proyecto tenmos lo end-points en un archivo aparte en la raíz

const { getIssuesFromGit } = require('./middlewares/GitIssues.middleware')
const { getReposFromGit } = require('./middlewares/gitRepos.middleware');
const { sendIssues } = require('./controllers/issues.controller');
const { sendRepos } = require('./controllers/repos.controller');


module.exports = function (app) {
    //ISUES

    app.get('/git-issues/:owner/:repo', getIssuesFromGit, sendIssues);

    //RREPOS
    app.get('/git-repos', getReposFromGit, sendRepos);
    
}

• Configuraciones en server.js:

const express = require('express');
const app = express();

const swaggerUi = require('swagger-ui-express')
const swaggerFile = require('./swagger/swagger_output.json')


require('dotenv').config();
require('./endpoints')(app)



const principalRoute = `${process.env.HOST}:${process.env.PORT}`;

app.use(
    '/api-docs',
    swaggerUi.serve,
    swaggerUi.setup(swaggerFile)
  );


app.listen( process.env.PORT,()=>{
    console.log(`Server is runing ${principalRoute}`);
})

Configuración package.jos y ejecutamos test-automático

Configuramos los scripts del archivo "package.json"

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js",
    "dev": "nodemon server.js",
    "swagger-autogen": "node ./swagger/swagger.js"
  }

Ejecutamos el swagger-autogen

npm run swagger-autogen

Inertar la información para la documentación.

Para personalizar y completar la info hay que hacerlo insertando comentarios de la siquiente forma en el endopoint o método correspondiente:

/**
     *  #swagger.description = 'Middleware: getIssuesFromGit -- recoge todas las tareas de git para un repositorio'
        
        #swagger.parameters['owner'] = { description: 'Usuario en GitHub' }
    
        #swagger.parameters['repo'] = {
                in: 'path',
                description: 'Repositorio usado en GitHub',
        } 
    */

  /* #swagger.responses[200] = {
        description1: 'User successfully obtained.',
        schema: {
            info: 'Información de la operación',
            data: [
    {
        "url": "https://api.github.com/repos/benawad/dogehouse/issues/2880",
        "repository_url": "https://api.github.com/repos/benawad/dogehouse",
        "labels_url": "https://api.github.com/repos/benawad/dogehouse/issues/2880/labels{/name}",
        "comments_url": "https://api.github.com/repos/benawad/dogehouse/issues/2880/comments",
        "events_url": "https://api.github.com/repos/benawad/dogehouse/issues/2880/events",
        "html_url": "https://github.com/benawad/dogehouse/issues/2880",
        "id": 1299767726,
        "node_id": "I_kwDOFCrI2M5NeOGu",
        "number": 2880,
        "title": "Help me, please!!!",
        ...
        },
    

Proyecto don de prueba

Aquí podrás descargar un pequeño proyecto en el que se prueba su uso

Visitar proyecto haciendo click aquí

Resultado