Blog

Tutorial Redocly: Cómo Usar la CLI de Redocly

Mark Ponomarev

Mark Ponomarev

9 June 2025

Tutorial Redocly: Cómo Usar la CLI de Redocly

¡Bienvenido a este completo tutorial sobre la CLI de Redocly! La CLI de Redocly es una herramienta de línea de comandos potente y todo en uno para definiciones de OpenAPI y Swagger. Te ayuda a construir, gestionar y verificar la calidad de tus descripciones de API a lo largo de todo el ciclo de vida de la API. Ya seas desarrollador, redactor técnico o gerente de producto de API, esta herramienta tiene algo para ti.

Este tutorial pretende ser una inmersión profunda en la CLI de Redocly, llevándote de ser un principiante a un usuario seguro. Cubriremos todo, desde la instalación hasta características avanzadas como reglas de linting personalizadas e integración con CI/CD. Al final de este tutorial, podrás integrar la CLI de Redocly en tu flujo de trabajo diario para mejorar la calidad y documentación de tu API.

💡
¿Quieres una excelente herramienta de prueba de API que genere hermosa Documentación de API?

¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje junto con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
botón

¿Qué es la CLI de Redocly?

Como se indica en su documentación oficial, la CLI de Redocly es tu "utilidad todo en uno para OpenAPI". Es compatible con OpenAPI 3.1, 3.0, 2.0 (Swagger heredado), AsyncAPI y más. Está diseñada para ayudarte con:

Esta herramienta está construida pensando en el rendimiento y la experiencia del usuario, proporcionando una ejecución rápida y mensajes de error legibles por humanos.

¿Por qué usar la CLI de Redocly?

En el mundo actual centrado en las API, mantener definiciones de API de alta calidad es crucial. La CLI de Redocly te ayuda a lograrlo mediante:

Qué cubrirá este tutorial

Este tutorial está estructurado para proporcionar una guía paso a paso para dominar la CLI de Redocly. Esto es lo que cubriremos:

¡Comencemos!

Capítulo 1: Primeros Pasos con la CLI de Redocly

Este capítulo te guiará a través de los primeros pasos para usar la CLI de Redocly, desde la instalación hasta la ejecución de tu primer comando.

Requisitos Previos

Antes de comenzar, asegúrate de tener lo siguiente instalado en tu sistema:

Instalación

Tienes varias opciones para instalar y usar la CLI de Redocly. Elige la que mejor se adapte a tus necesidades.

Uso de npx (Recomendado para uso rápido)

Si solo quieres probar la CLI de Redocly sin una instalación global, puedes usar npx, el ejecutor de paquetes de npm. Este comando descargará y ejecutará la última versión de la CLI de Redocly.

npx @redocly/cli@latest --version

Para usar cualquier comando de redocly, simplemente antepón npx @redocly/cli@latest. Por ejemplo:

npx @redocly/cli@latest lint openapi.yaml

Esta es una excelente manera de usar la CLI de Redocly en entornos de CI/CD o si no quieres llenar tu sistema con paquetes globales.

Instalación Global con npm

Para un uso regular, una instalación global es más conveniente. Hace que el comando redocly esté directamente disponible en tu terminal.

npm install -g @redocly/cli@latest

Después de la instalación, puedes verificarla comprobando la versión:

redocly --version

Ahora puedes ejecutar comandos como este:

redocly lint openapi.yaml

Uso de Docker

Si prefieres usar Docker, Redocly proporciona una imagen de Docker preconstruida. Esto es útil para aislar la herramienta de tu entorno local.

Primero, descarga la imagen desde Docker Hub:

docker pull redocly/cli

Para ejecutar un comando, necesitas montar tu directorio de trabajo actual (donde están tus archivos de API) como un volumen en el contenedor de Docker.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

En este comando, `$PWD` se refiere a tu directorio actual, que se monta en el directorio `/spec` dentro del contenedor. Luego debes referirte a tus archivos usando la ruta `/spec`.

Estructura Básica de Comandos

La estructura básica para usar la CLI de Redocly es:

redocly [comando] [argumentos] [opciones]

Siempre puedes obtener ayuda para un comando específico usando la opción --help:

redocly lint --help

Ahora que tienes la CLI de Redocly instalada y entiendes la estructura básica de comandos, pasemos a explorar sus potentes características.

Capítulo 2: Comandos y Características Principales

Este capítulo cubre los comandos principales de la CLI de Redocly. Exploraremos cómo hacer linting, gestionar, documentar y analizar tus definiciones de API. Para los ejemplos de este capítulo, usaremos un archivo openapi.yaml simple.

Creemos un archivo llamado openapi.yaml con el siguiente contenido:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Sección 2.1: Linting de tus Descripciones de API (`lint`)

El linting de API es el proceso de verificar tu archivo de definición de API en busca de consistencia, corrección y estilo. Te ayuda a aplicar pautas de diseño de API y a detectar posibles problemas antes de que lleguen a producción.

Uso Básico

El comando lint se utiliza para verificar tu definición de API contra un conjunto de reglas.

redocly lint openapi.yaml

Por defecto, redocly lint usa el conjunto de reglas recommended. Si nuestro openapi.yaml tiene problemas, la salida los detallará. Para nuestro archivo de ejemplo, la salida debería ser:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Configuración de Reglas

La CLI de Redocly viene con tres conjuntos de reglas configurables integrados:

Puedes especificar un conjunto de reglas con la opción --extends:

redocly lint openapi.yaml --extends=minimal

También puedes crear tus propios conjuntos de reglas personalizadas en un archivo de configuración redocly.yaml. Cubriremos esto en el Capítulo 3.

Formatos de Salida

El comando lint admite varios formatos de salida utilizando la opción --format, lo cual es muy útil para integrarse con otras herramientas.

Ejemplo de uso del formato stylish:

redocly lint openapi.yaml --format=stylish

Ignorar Problemas

A veces puede que necesites ignorar un problema específico. Puedes generar un archivo .redocly.lint-ignore.yaml para suprimir errores y advertencias.

redocly lint openapi.yaml --generate-ignore-file

Este comando creará un archivo de ignorados. Si ejecutas lint de nuevo, los problemas listados en este archivo serán ignorados. Esto te da un control granular sobre el proceso de linting.

Sección 2.2: Gestión de Descripciones de API con bundle y split

A medida que tu API crece, gestionar un único archivo OpenAPI monolítico se vuelve engorroso. La CLI de Redocly proporciona dos comandos para ayudar con esto: split y bundle.

Dividir un Archivo OpenAPI Grande (`split`)

El comando split te permite dividir un archivo de definición de API grande en una estructura de múltiples archivos más manejable. Extrae componentes, rutas y ejemplos en archivos y carpetas separadas.

Dividamos nuestro openapi.yaml:

redocly split openapi.yaml --outDir=split-api

Este comando creará un directorio split-api con la siguiente estructura:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

El nuevo openapi.yaml en split-api ahora usará `$ref` para enlazar a los archivos externos:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

Esto hace que sea mucho más fácil gestionar diferentes partes de tu API.

Empaquetar Múltiples Archivos (`bundle`)

El comando bundle hace lo contrario de split. Toma un archivo de definición de API raíz y resuelve todas las referencias `$ref` locales para crear un único archivo autocontenido. Esto es útil para herramientas que no admiten definiciones de múltiples archivos.

Empaquetemos nuestra API dividida de nuevo en un solo archivo:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

El bundled-api.yaml tendrá el mismo contenido que nuestro openapi.yaml original.

Desreferenciación

El comando bundle también puede crear un archivo completamente desreferenciado, donde todas las referencias `$ref` (incluidas las remotas) se resuelven y se reemplazan con su contenido.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

Esto puede ser útil, pero ten en cuenta que puede hacer que el archivo sea mucho más grande y que las referencias circulares pueden causar problemas con la salida JSON.

Sección 2.3: Generación de Documentación de API (`build-docs`)

Una de las características más potentes de la CLI de Redocly es su capacidad para generar documentación de referencia de API hermosa e interactiva utilizando el motor de código abierto Redoc.

Uso Básico

Para generar documentación, usa el comando build-docs:

redocly build-docs openapi.yaml

Esto creará un archivo redoc-static.html en tu directorio actual. Ábrelo en tu navegador para ver tu documentación.

Puedes especificar un archivo de salida diferente con la opción -o o --output:

redocly build-docs openapi.yaml -o my-api-docs.html

Personalización de la Salida

Puedes personalizar la apariencia de tu documentación usando la opción --theme.openapi. Esto te permite cambiar colores, fuentes e incluso deshabilitar partes de la interfaz de usuario como la barra de búsqueda.

Por ejemplo, para deshabilitar la barra de búsqueda:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

Puedes encontrar todas las opciones de tema disponibles en la documentación oficial de Redocly.

Para un control aún mayor, puedes proporcionar tu propia plantilla Handlebars para renderizar la documentación. Esta es una característica avanzada que permite una personalización completa de la salida HTML.

Sección 2.4: Obtención de Estadísticas de API (`stats`)

El comando stats proporciona métricas útiles sobre tu definición de API, como el número de rutas, operaciones, esquemas y más.

Cómo obtener Estadísticas

Para obtener estadísticas de tu API, simplemente ejecuta:

redocly stats openapi.yaml

La salida predeterminada está en formato stylish:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Diferentes Formatos

Al igual que el comando lint, stats admite diferentes formatos de salida con la opción --format. Los formatos json y markdown son particularmente útiles.

redocly stats openapi.yaml --format=json

Esto es genial para alimentar las estadísticas a otras herramientas o paneles.

redocly stats openapi.yaml --format=markdown

Esto genera una tabla Markdown, que es perfecta para informes o para usar en resúmenes de GitHub Actions, como veremos en el próximo capítulo.

Capítulo 3: Temas Avanzados

En este capítulo, profundizaremos en algunas de las características más avanzadas de la CLI de Redocly, incluido el potente archivo de configuración y la integración con pipelines de CI/CD.

Archivo de Configuración (`redocly.yaml`)

Si bien puedes usar la CLI de Redocly completamente desde la línea de comandos, un archivo de configuración redocly.yaml te permite almacenar tu configuración en un solo lugar, haciendo que tus comandos sean más cortos y tu configuración reutilizable.

Creemos un archivo redocly.yaml en la raíz de nuestro proyecto:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Estructura del Archivo de Configuración

Uso de Alias de API

Con la sección apis configurada, ahora puedes usar el alias main en lugar de la ruta del archivo en tus comandos:

redocly lint main
redocly stats main
redocly build-docs main

Esto es especialmente útil cuando tienes múltiples APIs en tu proyecto. Si ejecutas redocly lint sin argumentos, hará linting de todas las APIs definidas en la sección apis.

Integración Continua (CI)

Integrar la CLI de Redocly en tu pipeline de CI/CD es una forma fantástica de automatizar los controles de calidad de la API. Aquí tienes un ejemplo de cómo usarla con GitHub Actions.

Crea un archivo llamado .github/workflows/redocly.yaml:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

Este flujo de trabajo de GitHub Actions hace lo siguiente:

  1. Se activa en cada push y pull request a la rama main.
  2. Clona tu código.
  3. Instala Node.js y la CLI de Redocly.
  4. Ejecuta el comando lint con el formato github-actions. Esto anotará automáticamente cualquier problema directamente en tus pull requests.
  5. Ejecuta el comando stats con el formato markdown y añade la salida al resumen del trabajo, dándote un buen informe en cada ejecución.

Esta es una forma potente de asegurar que tus definiciones de API estén siempre en buen estado.

Capítulo 4: Ejemplo Práctico: Un Flujo de Trabajo Completo

En este último capítulo, pondremos todo lo que hemos aprendido junto y recorreremos un flujo de trabajo completo y práctico. Haremos lo siguiente:

  1. Crear una estructura de proyecto con una definición de API de múltiples archivos.
  2. Crear un archivo de configuración redocly.yaml.
  3. Hacer linting de la definición de API usando nuestra configuración personalizada.
  4. Empaquetar la API en un solo archivo.
  5. Generar documentación de API.

1. Configuración del Proyecto

Creemos un nuevo directorio para nuestro proyecto y configuremos la estructura de archivos.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Ahora, creemos los archivos de API divididos.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (nuestro punto de entrada principal):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. Crear redocly.yaml

Ahora, creemos nuestro archivo de configuración en la raíz del directorio redocly-petstore.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

En esta configuración, hemos definido un alias petstore@v1 para nuestra API y hemos añadido algunas reglas de linting personalizadas.

3. Hacer Linting de la API

Ahora, hagamos linting de nuestra API usando nuestra nueva configuración.

redocly lint petstore@v1

Verás algunos errores y advertencias porque nuestra API aún no cumple con todas nuestras nuevas reglas. Por ejemplo, no tenemos etiquetas con descripciones. Esto demuestra cómo puedes aplicar tu propia guía de estilo de API.

4. Empaquetar la API

A continuación, empaquetemos nuestra API de múltiples archivos en un único archivo distribuible.

redocly bundle petstore@v1 -o dist/petstore.yaml

Esto creará un directorio dist con un archivo petstore.yaml dentro, conteniendo la definición de API completamente resuelta.

5. Generar Documentación

Finalmente, generemos nuestra documentación de API.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

Esto creará dist/petstore-docs.html. Abre este archivo en tu navegador para ver tu hermosa e interactiva documentación de API.

¡Y ahí lo tienes! Un flujo de trabajo completo desde una definición de API estructurada y de múltiples archivos hasta un archivo empaquetado y documentación profesional, todo gestionado con la CLI de Redocly.

Conclusión

En este tutorial, hemos realizado una inmersión profunda en la CLI de Redocly. Comenzamos con los conceptos básicos de instalación y comandos principales, luego pasamos a temas avanzados como la configuración y la integración con CI, y finalmente recorrimos un flujo de trabajo completo y práctico.

Ahora deberías tener una comprensión sólida de cómo usar la CLI de Redocly para:

La CLI de Redocly es una herramienta versátil y potente que puede mejorar significativamente tu flujo de trabajo de desarrollo de API. Te animo a explorar sus características más a fondo e integrarla en tus proyectos.

Recursos Adicionales

Gracias por seguir este tutorial. ¡Feliz construcción de APIs!

💡
¿Quieres una excelente herramienta de prueba de API que genere hermosa Documentación de API?

¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje junto con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
botón

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar