Documentación de nuestra API

Para documentar la API he desarrollado con mi hermano una librería open source que sirve para documentar tus endpoints mediante comentarios siguiendo la especificación OpenApi 3 de swagger sin tener que escribir el YAML o JSON.
Os dejo el repositorio: https://github.com/BRIKEV/express-jsdoc-swagger
La docu: https://brikev.github.io/express-jsdoc-swagger-docs/#/

Para no instalar body-parser ya que desde express 4.16.0 lo incluye tuve que agregar estas líneas en api/index.js

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

Si tienen problemas con el require de nanoid instalen la versión ^2.1.7. npm i [email protected]

Estoy llorando en ver algo tan organizado

Reto cumplido:

Hay una mejor opción para esto

    if (body.id) {
      user.id = body.id;
    } else {
      user.id = nanoid();
    }

Agregar la validación dentro del mismo objeto

const user = {
      name: body.name,
      ...(body.id ? {id : body.id} : {id : nanoid()})
    };

Postman te genera la documentación de tu API.

Yo vengo del mundo frontend, pero hace un tiempo trabaje con un ingeniero en sistemas. Yo hacia lo mio y el el backend, me sorprendió porque usaba Java Springs junto con Jenkins y la api que el iba desarrollando se le auto-documentaba con swagger. Supongo que node aun no existe algo como esto…ahi entendi porque algunos dicen que Java es el lenguaje mas profesional de todos xD. Igual yo me quedo con node y js toda la vida, poder desarrollar todo el stack con un solo lenguaje no tiene precio.

En vez de utilizar bodyparser utilize la funcion de express
Nos ahorra el tener que instalar otro paquete

app.use(express.json());

nanoid is not a function

const { nanoid } = require('nanoid');

Me costo un poquito entender como funcionaba, pero lo logre!

Algo que pense que nunca aprenderia de repente aparecio y hoy agradezco por haber aprendido que siempre va a servir de una forma u otra 💚

También pueden utilizar los middlewares que vienen dentro del core de Express:

app.use(express.urlencoded({
  extended: true
}));

express.urlencoded([options])

app.use(express.json());

express.json([options])

Se puede exportar la documentación en markdown?

Con la version más reciente de nanoid (4.0.0) arroja un error al usar require para importarlo.

Para solucionarlo hay que modificar el api para que soporte ES6

import { nanoid } from "nanoid";

Aca unos links de ayuda:

https://bobbyhadz.com/blog/javascript-error-err-require-esm-require-of-es-module-not-supported

https://bobbyhadz.com/blog/javascript-requested-module-not-provide-export-named-default

Mi archivo de rutas, un poco mas organizado XD

excelente… de gran ayuda la documentaci[on

Para la documentación yo me apoye con lo siguiente:

https://app.swaggerhub.com/help/ui/editor

Aqui pueden abrir cuenta

https://app.swaggerhub.com/

Y es mas facil hacer la documentacion,

Luego se exporta y se copia en el archivo swagger.json

Y se puede visualizar desde nuestra API

http://localhost:3000/api-docs/#/

En la versión de openapi “3.0.3”, necesitan ir a la herramienta de Swagger y luego exportar el documento como .json para que funcione todo

Y de dónde sale bodyParser?? Teníamos que haber hecho eso? Igual podríamos haber sacado un conejo de la chistera y lo mismo acertamos tb…

Yo estoy usando https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client

como opcion a insomnia y postman 😃
es un plugin para VSCode

Muy interesante. Aunque no me quedó muy claro, porque el upsert, no tiene en cuenta las actualizaciones por PUT. Creo que faltó detallar esa parte un poco mas.

Yo lo realice así:

store/dummy.js

controller.js

network.js

Muy buena opción para documentar nuestras aplicaciones. Postman también ofrece ésta opción.

Podrias no instalar body-parser y utilizar la misma libreria de express con express.json()

se puede usar la extensión Thunder client de vsc, para no estar cambiando de ventanas y posterior ya exportarla a postman o insomnia

Excelente, super útil

Reto cumplido.

swagger-jsdoc y swagger-ui-express para realizar la documentación a manera de comentario sobre cada ruta

Si estan usando Typescript yo lo implemente de la siguiente manera:
Instale los types

npm install @types/swagger-ui-express -D

index.ts

import swaggerUi  from 'swagger-ui-express';

import * as swaggerDoc from "./swagger.json";

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

En el tsconfig.json

"compilerOptions": {
"resolveJsonModule" : true, // agregar esta linea
}

Si alguien más tuvo problemas (como yo) para configurar bien esta API, les dejo como debería quedar (No es perfecta, pero funciona):

{
  "swagger": "2.0",
  "info": {
    "description": "Una red social en NodeJS",
    "version": "1.0.0",
    "title": "RedSocialNode"
  },
  "host": "localhost:3000",
  "basePath": "/api",
  "tags": [
    {
      "name": "user",
      "description": "Operaciones sobre el usuario"
    }
  ],
  "schemes": [
    "http"
  ],
  "paths": {
    "/user": {
      "get": {
        "tags": [
          "user"
        ],
        "summary": "Lista los usuarios",
        "operationId": "listUser",
        "responses": {
          "default": {
            "description": "Lista de usuarios"
          }
        }
      },
      "post": {
        "tags": [
          "user"
        ],
        "summary": "Crea un usuario",
        "description": "Crea un usuario en nuestra app",
        "operationId": "createUser",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "Usuario creado",
            "required": true,
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "Operación exitosa"
          }
        }
      },
      "put": {
        "tags": [
          "user"
        ],
        "summary": "Actualiza un usuario",
        "description": "Actualiza un usuario en nuestra app",
        "operationId": "upsertUser",
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "Usuario actualizado",
            "required": true,
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "Usuario actualizado con éxito"
          }
        }
      }
    },
    "/user/{userId}": {
      "delete": {
        "tags": [
          "user"
        ],
        "summary": "Elimina a un usuario",
        "description": "Elimina a un usuario de nuestra app",
        "operationId": "deleteUser",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "type": "string",
            "description": "Usuario eliminado",
            "required": true
          }
        ],
        "responses": {
          "default": {
            "description": "Usuario eliminado con éxito"
          }
        }
      },
      "get": {
        "tags": [
          "user"
        ],
        "summary": "Busca a un usuario",
        "description": "Busca a un usuario de nuestra app",
        "operationId": "getUser",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "type": "string",
            "description": "Usuario buscado",
            "required": true
          }
        ],
        "responses": {
          "default": {
            "description": "Usuario encontrado con éxito"
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "username": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    },
    "ApiResponse": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "type": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  },
  "externalDocs": {
    "description": "Find out more about Swagger",
    "url": "https://swagger.io"
  }
}

Se ve muy elegante

Antes, para poder obtener el cuerpo de una petición POST en nuestra aplicación usabamos el modulo body-parser como middleware para facilmente leer el cuerpo de la peticion a travez del req.body
Instalabamos el módulo con:
npm install --save body-parser

y usabamos la línea:

app.use(bodyparser.json());

Ahora sólo, sin instalar body-parser, podemos usar la siguiente línea:

app.use(express.json());

Ya que Express lo ha incluido por defecto en su paquete.

Tomado de:
https://platzi.com/tutoriales/1689-backend-js/6598-es-necesario-instalar-el-modulo-body-parser/

✌

Muy satisfecha con lo que voy aprendiendo !

el documentar es algo muy muy importante en cualquier desarrollo

excelente

el documentar es algo muy muy importante en cualquier desarrollo

ufff excelente tip Carlos, saludos.

Esta clase es mi preferida de la vida …

Excelente herramienta y cómo lo explica. Ideal usar swagger cuando tenemos un equipo de frontend consumiendo nuestra API.

La forma en la que llama funciones en las rutas esa si no me la sabia profe muy buen trabajo

La documentación es supremamente importante para llevar un correcto desarrollo y una gran forma de compartir código con otros desarrolladores.

Este profesor es el mejor!!!

Aguien le aparece este error al intentar abrir la documentación del API en local:

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: “2.0” and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

Excelente ayuda

Genial 😃 👌😉

Que bien aprender todo esto =)

Reto cumplido
Les dejo la parte del path del YAML

paths:
  /user:
    get:
      tags:
      - "user"
      summary: "list users"
      operationId: "listUser"
      responses:
        default:
          description: "users list"
    post:
      tags:
      - "user"
      summary: "Create user"
      description: "Create an user in the app"
      operationId: "createUser"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Created user object"
        required: true
        schema:
          $ref: "#/definitions/User"
      responses:
        default:
          description: "successful operation"
  /user/{id}:
    get:
      tags:
      - "user"
      summary: "get  specific user"
      operationId: "getUser"
      parameters:
      - in: "path"
        name: "id"
        required: true
        type: "string"
        description: "Numeric ID of the user to get"
      responses:
        default:
          description: "user information"
    delete:
      tags:
      - "user"
      summary: "remove specific user"
      description: "remove specific user from database"
      parameters:
      - in: "path"
        name: "id"
        required: true
        type: "string"
        description: "Numeric ID of the user to delete"
      responses:
        default:
          description: "succesful operation"

Añadí el metodo de remove

Para quienes no les funcione el require de nanoid, háganlo así:

const {nanoid} = require('nanoid')

Para documentar la api he utilizado swagger-ui-express y swagger-jsdoc (Puedes usar yaml,json y comentarios jsdoc) 😃

Aqui les dejo mi repositorio por si quieren ver como lo he dejado.
https://github.com/lskywolfll/Posts-nodejs

Una pregunta… No consigo que me guarde los nombres de los usuarios. Al descargarme el proyecto del profesor tampoco me funciona.

Puede ser por el tipo de Cliente que estoy usando?

{
"error": false,
"status": 200,
"body":[
{
"id": "1",
"name": "Carlos"
},
{
"id": "OJlnxx0WjtanBOxaJTutm"
},
{
"id": "vWBpER0heNNzTBMtcXFtG"
}
]
}```

nanoid, libreria para generar ids body-parser, para trabajar con json pero mejor usar el de express nativo