A煤n no tienes acceso a esta clase

Crea una cuenta y contin煤a viendo este curso

Documentaci贸n de nuestra API

6/29
Recursos

Aportes 46

Preguntas 4

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸n.

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 }));

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鈥hi 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.

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])

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

app.use(express.json());

Se puede exportar la documentaci贸n en markdown?

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

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/#/

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 馃挌

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

nanoid is not a function

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

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()

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

como opcion a insomnia y postman 馃槂
es un plugin para VSCode

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