Documentar tu API de Express con TypeScript usando OpenAPI (Swagger)

En la serie Creación de una API REST con Express y TypeScript construimos una API básica con Express y TypeScript como plantilla para futuros proyectos. El código completo está disponible en el repositorio de GitHub de Analytics Lane.

Sin embargo, en aquella ocasión dejamos pendiente un aspecto fundamental: la documentación de la API. Tener una buena documentación es clave para que otros desarrolladores —o incluso nosotros mismos en el futuro— puedan entender rápidamente cómo consumirla, sin necesidad de revisar el código fuente.

Hoy en día, la mejor forma de documentar una API es utilizando el estándar OpenAPI 3.0, ampliamente adoptado en el ecosistema web. Para integrarlo fácilmente en un proyecto Express, utilizaremos dos librerías muy conocidas:

• swagger-jsdoc: genera automáticamente el esquema OpenAPI a partir de anotaciones en el código.
• swagger-ui-express: ofrece una interfaz web interactiva para consultar y probar los endpoints de la API.

En esta entrada veremos paso a paso cómo:

1. Configurar Swagger en nuestro proyecto expresslanets.
2. Documentar los endpoints mediante anotaciones JSDoc.
3. Organizar el proyecto para mantener la documentación limpia y escalable.
4. Aplicar buenas prácticas en producción: cuándo y cómo desactivar o proteger la documentación.

Preparar el proyecto

Partiremos del proyecto creado en la serie anterior: un servidor Express en TypeScript disponible en el GitHub de Analytics Lane.

El primer paso será instalar las dependencias necesarias para integrar Swagger en el proyecto:

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

Configuración de Swagger en expresslanets

Una vez instaladas las nuevas dependencias, el siguiente paso es crear el archivo de configuración de Swagger. En el proyecto expresslanets, añadimos un nuevo archivo en src/config/swagger.ts con la configuración base:

import swaggerJsdoc from 'swagger-jsdoc';

import { version } from '../../package.json';

const swaggerOptions: swaggerJsdoc.Options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API de ejemplo con Express + TypeScript',
      version: version,
      description: 'Documentación generada automáticamente con Swagger',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  // Aquí indicamos dónde buscar las anotaciones
  apis: ['./src/routes/**/*.ts'],
};

export const swaggerSpec = swaggerJsdoc(swaggerOptions);

En este archivo definimos los metadatos básicos de la API (título, versión y descripción), así como las rutas donde Swagger buscará las anotaciones que usaremos más adelante para documentar los endpoints.

Integrar Swagger en la aplicación

Con la configuración lista, el siguiente paso es integrar Swagger en el servidor Express para poder acceder a la interfaz de documentación.

Abrimos el archivo src/server.ts y añadimos las siguientes líneas dentro del constructor de la clase que inicializa la aplicación:

this._app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
this._app.get('/api-docs.json', (_req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

La primera línea monta la interfaz interactiva de Swagger en la ruta /api-docs, mientras que la segunda expone el esquema OpenAPI en formato JSON en /api-docs.json.

De esta manera, al ejecutar el proyecto podrás acceder a la documentación en tu navegador en: http://localhost:3000/api-docs. Por ahora, la interfaz aparecerá vacía porque aún no hemos añadido anotaciones a los endpoints. En la siguiente sección aprenderemos cómo documentarlos correctamente.

Documentar los endpoints con JSDoc

Una vez configurado Swagger, ya podemos comenzar a documentar los endpoints de nuestra API.
Para ello, basta con añadir comentarios JSDoc con la etiqueta @openapi justo encima de cada ruta que queramos documentar.

Por ejemplo, en el archivo src/routes/auth.ts podríamos documentar un endpoint de autenticación de la siguiente forma:

import { Router, Request, Response } from 'express';
import { sign, SignOptions } from 'jsonwebtoken';

import Logins from '../entities/logins';
import verifytoken from '../middlewares/verifytoken';
import datasource from '../config/datasource';
import { responseAndLogger } from '../config/logger';

const router = Router();

const secret = String(process.env.TOKEN_SECRET);
const expiresIn = (process.env.EXPIRES ? String(process.env.EXPIRES) : '15m') as SignOptions['expiresIn'];

/**
 * @openapi
 * /auth/login:
 *   post:
 *     tags:
 *       - Auth
 *     summary: Login
 *     description: Login
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *     responses:
 *       200:
 *         description: Token
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 token:
 *                   type: string
 *       400:
 *         description: Bad request
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 */router.post('/login', (req: Request, res: Response) => {
  const username = String(req.body.username);
  const password = String(req.body.password);

  datasource
    .getRepository(Logins)
    .findOneByOrFail({ username })
    .then((user) => {
      if (user.validatePassword(password)) {
        sign({ id: user.id, username: user.username }, secret, { expiresIn }, (err, token) => {
          if (err) {
            responseAndLogger(res, 'It was not possible to generate the token', 400);
          }

          return res.send({ token });
        });
      } else {
        responseAndLogger(res, 'Invalid password', 400);
      }
    })
    .catch(() => responseAndLogger(res, 'Invalid user', 400));
});

/**
 * @openapi
 * /auth/info:
 *   get:
 *     tags:
 *       - Auth
 *     summary: Get info
 *     description: Get info
 *     responses:
 *       200:
 *         description: Info
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: integer
 *                 username:
 *                   type: string
 *       400:
 *         description: Bad request
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 */router.get('/info', [verifytoken], (_req: Request, res: Response) => {
  res.send(res.locals.payload);
});

/**
 * @openapi
 * /auth/register:
 *   post:
 *     tags:
 *       - Auth
 *     summary: Register
 *     description: Register
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *     responses:
 *       200:
 *         description: User
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: integer
 *                 username:
 *                   type: string
 *       400:
 *         description: Bad request
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 */router.post('/register', (req: Request, res: Response) => {
  const username = String(req.body.username);
  const password = String(req.body.password);

  datasource
    .getRepository(Logins)
    .findOneByOrFail({ username })
    .then(() => {
      responseAndLogger(res, 'User already exists', 406);
    })
    .catch(() => {
      const user = new Logins();
      user.username = username;
      user.password = password;

      datasource
        .getRepository(Logins)
        .save(user)
        .then((user) => res.send(user))
        .catch((error) => responseAndLogger(res, error.message, 500));
    });
});

export default router;

En este ejemplo, la documentación describe claramente el propósito de cada uno de los endpoints, los campos esperados en el cuerpo de la petición y las posibles respuestas.

Al volver a abrir Swagger UI, el endpoint /auth/login aparecerá documentado con sus parámetros, tipos de datos, ejemplos y descripciones —todo generado automáticamente a partir de las anotaciones en el código—.

Buenas prácticas en producción

Ahora que nuestra API ya cuenta con documentación interactiva, es importante recordar que no siempre conviene exponer Swagger en entornos de producción.

Aunque es extremadamente útil durante el desarrollo, dejar la documentación abierta públicamente puede revelar detalles sensibles sobre la estructura de la API, lo cual supone un posible riesgo de seguridad.

Existen principalmente dos enfoques recomendados para mitigar este riesgo:

1. Desactivar Swagger en producción (opción más común y segura).
2. Proteger Swagger con autenticación básica o un middleware de acceso restringido.

La forma más sencilla de implementar el primer enfoque es condicionar la carga de Swagger según el entorno. Para ello, podemos modificar nuestro servidor (src/server.ts) de la siguiente forma:

const NODE_ENV = process.env.NODE_ENV || 'development';

if (NODE_ENV === 'development') {
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  app.get('/api-docs.json', (_req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
  });
}

Con esta configuración, la ruta /api-docs solo estará disponible cuando NODE_ENV=development. En producción, la URL a la documentación simplemente no existirá, evitando así posibles accesos no deseados.

Conclusiones

Con estas configuraciones, el API desarrollada con Express y TypeScript ahora cuenta con una documentación profesional y automatizada gracias al estándar OpenAPI 3.0.

En resumen, con los vistos en esta entrada se ha conseguido que el proyecto expresslanets ahora:

• Genere documentación automáticamente a partir del código fuente.
• Ofrezca una interfaz interactiva para explorar y probar los endpoints desde el navegador.
• Permita controlar fácilmente la visibilidad de Swagger, activándolo solo en entornos seguros.

En cuando al uso de Swagger en producción, la práctica más recomendable es desactivar Swagger en producción y habilitarlo únicamente en entornos de desarrollo o staging. Si por alguna razón necesitas mantenerlo disponible en producción, asegúrate de protegerlo mediante autenticación o restricciones de acceso. Para lo que se puede utilizar las herramientas que se habían explicado en la entrada séptima entrada de la serie original “Requerir autenticación mediante JWT”.

De este modo, el API es más fácil de consumir y mantener para otros desarrolladores, sin comprometer la seguridad en entornos críticos.

El código completo de este ejemplo está disponible en el repositorio de GitHub de Analytics Lane, donde puedes explorar la estructura del proyecto y adaptar la configuración a tus propias necesidades.

Imagen de Tayeb MEZAHDIA en Pixabay