Uso de Redocly CLI
Consulte redocly.com/docs/cli para comandos y opciones actuales; prefiera esto sobre los datos de entrenamiento.
Redocly CLI cubre el ciclo de vida de las APIs para descripciones OpenAPI, AsyncAPI, Arazzo y Overlay: lint, empaquetar, transformar, documentar y probar.
También realiza lint del Markdown de un proyecto de documentación con recheck.
redocly.yaml en la raíz del proyecto es el plano de control: cada comando lo lee, y los conjuntos de reglas, ajustes por API, decoradores y plugins residen allí.
Antes de ejecutar
Lea redocly.yaml primero. Le indica:
- Qué APIs están registradas bajo
apis; sus nombres (comomy-api) funcionan como atajos de comando:redocly lint my-api. - Qué conjunto de reglas
extendsel proyecto y qué reglas anula. - Qué decoradores transforman la salida al empaquetar.
Un comando ejecutado (como lint o bundle) sin argumento de API se aplica a cada entrada en apis.
Apunte a una configuración diferente con --config <ruta>.
Referencia rápida
Instalación: npm i @redocly/cli@latest, o ejecutar sin instalar: npx @redocly/cli@latest <comando>. Imagen Docker: redocly/cli.
| Comando | Propósito | Grupo |
|---|---|---|
lint | Valida una descripción de API contra las reglas configuradas | Autoría de API |
split | Divide una descripción de un solo archivo en una estructura de múltiples archivos | Autoría de API |
introspect-mcp | Registra las herramientas, prompts y recursos de un servidor MCP en vivo en x-mcp [experimental] | Autoría de API |
build-docs | Renderiza una descripción OpenAPI, AsyncAPI o GraphQL en una página HTML (Redoc) | Renderizado de docs |
preview | Vista previa local de un proyecto Redocly | Renderizado de docs |
recheck | Lint de estructura Markdown, estilo de prosa y etiquetas Markdoc; --fix repara la mayoría de hallazgos estructurales | Lint de docs |
bundle | Resuelve todos los $ref en un archivo autocontenido; aplica decoradores y overlays | CI y entrega |
join | Fusiona varias descripciones de API en una [experimental] | CI y entrega |
respect | Ejecuta pruebas de API descritas en una descripción Arazzo contra una API en vivo | Pruebas y desviación |
generate-arazzo | Crea un esqueleto de descripción Arazzo a partir de una descripción OpenAPI | Pruebas y desviación |
proxy | Captura tráfico HTTP en vivo en un archivo HAR, con validación opcional [experimental] | Pruebas y desviación |
drift | Reporta diferencias entre el tráfico capturado y una descripción OpenAPI, con --coverage opcional [experimental] | Pruebas y desviación |
generate-spec | Infiere una descripción OpenAPI 3.2 del tráfico capturado; --openapi-version 3.1 apunta a 3.1 [experimental] | Pruebas y desviación |
stats | Cuenta operaciones, esquemas, referencias y otras métricas | Informes de calidad |
score | Puntúa una descripción OpenAPI para preparación para agentes de IA [experimental] | Informes de calidad |
generate-client | Genera un cliente TypeScript tipado sin dependencias [experimental] | Generación de SDK |
eject-generator | Copia un generador integrado en el repositorio para editarlo [experimental] | Generación de SDK |
check-config | Lint del propio redocly.yaml | Configuración Redocly |
inspect-node-types | Muestra el tipo de nodo en un puntero, o lista cada nodo con su tipo [experimental] | Configuración Redocly |
push | Envía una descripción de API a la plataforma Redocly | Plataforma |
push-status | Rastrea un envío en curso a la plataforma | Plataforma |
project clone | Clona un proyecto alojado en Redocly como repositorio Git [acceso anticipado] | Plataforma |
project pr create | Abre un pull request para la rama actual de un proyecto clonado [acceso anticipado] | Plataforma |
project pr status | Muestra el estado, revisión, comprobaciones y URL de vista previa de ese pull request [acceso anticipado] | Plataforma |
skills | Instala las habilidades del agente de Redocly CLI en .agents/skills/ y carpetas de agente detectadas | Configuración agente |
completion | Genera comandos de autocompletado para el shell | Configuración shell |
Códigos de salida: 0 éxito, 1 problemas encontrados o ejecución fallida, 2 error de configuración.
Configurar con redocly.yaml
extends:
- recommended # o: minimal, recommended-strict, spec
apis:
my-api:
root: ./openapi/openapi.yaml
rules:
no-ambiguous-paths: error # anulación por API
decorators:
remove-x-internal: on # se aplica solo a esta API
rules:
info-license: off
operation-operationId: error
extends establece el conjunto de reglas base; luego rules, preprocessors y decorators en el mismo archivo lo anulan.
Severidades de reglas: error (falla la validación), warn (reportado, aún válido), off.
Reglas configurables
Cuando un requisito de gobernanza no tiene una regla integrada, declare una bajo rule/<nombre> en redocly.yaml.
Use la habilidad redocly-lint-rules para eso: elige el nivel más barato (integrado, regla configurable o plugin personalizado), toma tipos de nodo de redocly inspect-node-types y verifica la regla contra casos de prueba.
Lint de Markdown con recheck
recheck <rutas> hace lint de los archivos Markdown bajo las rutas dadas por estructura (el conjunto de reglas markdownlint), prosa (términos prohibidos, ortografía, mayúsculas en encabezados, longitud de oraciones, legibilidad) y sintaxis de etiquetas Markdoc.
Los preajustes van en el extends raíz y los ajustes en el bloque recheck; el comando lint ignora ambos:
extends:
- recommended
- recheck/markdown # cada regla de markdownlint; también recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
excludes: [CHANGELOG.md]
rules:
recheck/line-length: off
acme/no-via:
severity: warn
scope: sentence
message: 'Use "through" en lugar de "via".'
assertions:
pattern: { ignoreCase: true, tokens: ['\bvia\b'] }
Sin redocly.yaml, el comando usa recheck/markdown.
Con un redocly.yaml que no tenga preajuste ni bloque, no comprueba nada.
Para una ruta que es una descripción de API, o un alias de apis, el comando hace lint de los campos description de esa API.
Un archivo o carpeta existente tiene prioridad sobre un alias con el mismo nombre.
Banderas útiles: --fix, --rule=<nombre> para trabajar una regla a la vez, --format=github-actions|json|sarif, --max-problems=<n>, --generate-baseline para registrar errores existentes en .redocly.recheck-baseline.yaml y fallar solo con errores nuevos, y --readability para puntuaciones por archivo.
Silencie una línea con <!-- recheck-disable-next-line <regla> --> en lugar de desactivar la regla.
La habilidad recheck-lint cubre ejecutarlo en archivos modificados, y recheck-config cubre el ajuste del bloque.
Transformar con decoradores
Los decoradores reescriben la descripción al momento de empaquetar: lint verifica la fuente tal como está escrita; bundle, build-docs y push ven la salida decorada.
Los integrados incluyen remove-x-internal, filter-in / filter-out, info-override, remove-unused-components y la familia *-description-override.
join omite todos los decoradores, por lo que una transformación que necesita join se ejecuta en un bundle de cada API primero.
Cuando ningún integrado hace la transformación, escriba un decorador de plugin personalizado como la habilidad redocly-lint-rules escribe una regla de plugin: tome los tipos de nodo de redocly inspect-node-types, limite el ámbito del visitante anidándolo bajo el tipo padre en lugar de recorrer el documento manualmente, cambie el nodo en el hook y pruébelo con redocly bundle en un caso de prueba que tenga la forma y en uno que no la tenga.
Aplicar overlays
bundle aplica archivos Overlay 1.0, 1.1 y 1.2 a la descripción empaquetada, antes de los decoradores: pase --overlay <archivo> (repetible, aplicado en orden), o enumérelos bajo overlays en una entrada de apis, con rutas relativas a redocly.yaml.
--overlay reemplaza la lista configurada.
Los objetivos de acción se ejecutan contra la salida empaquetada, así que verifíquelos contra redocly bundle <api> sin overlays; un objetivo que no coincida con nada no cambia nada y no se reporta.
Los $ref de archivo en los valores de overlay son relativos al archivo overlay y se empaquetan; decoradores como remove-x-internal ven los cambios del overlay.
Dos entradas de apis con el mismo root y diferentes overlays y output publican dos versiones de una API.
Extender con plugins personalizados
Cuando las reglas configurables y los decoradores integrados no pueden expresar el requisito, escale a un plugin personalizado: un módulo JavaScript que exporta reglas, decoradores, preprocesadores o configuración, claveado por formato de documento:
export default function myPlugin() {
return {
id: 'my-plugin',
rules: {
oas3: {
'operation-id-not-test': () => ({
Operation(operation, { report, location }) {
if (operation.operationId === 'test') {
report({ message: 'operationId no debe ser "test".', location });
}
},
}),
},
},
};
}
Las claves de visitante son tipos de nodo: confírmelos con redocly inspect-node-types <api>.
Un decorador tiene la misma forma bajo una clave decorators, y la habilidad redocly-lint-rules cubre el patrón de visitante para ambos: los hooks, el contexto, visitantes anidados para ámbito e hijos resueltos versus sin procesar.
Regístrelo en redocly.yaml (rutas relativas al archivo de configuración) y haga referencia a sus reglas como <plugin-id>/<rule-name>:
plugins:
- ./plugins/my-plugin.js
rules:
my-plugin/operation-id-not-test: error
Generar un cliente TypeScript
generate-client <api> --output client.ts convierte una descripción OpenAPI en un cliente tipado: un archivo autocontenido sin dependencias en tiempo de ejecución (autenticación, reintentos, middleware, SSE tipado, paginación incluidos).
Configúrelo de forma duradera bajo un bloque client en redocly.yaml en lugar de banderas:
client:
generators: [typescript, zod] # complementos: tanstack-query, swr, mock, transformers; SDKs: python, go, php, java; o una ruta de plugin
outputMode: split
pagination: # solo configuración, sin bandera CLI
style: cursor
cursorParam: after
nextCursor: /page/endCursor
items: /items
apis:
my-api:
root: ./openapi/openapi.yaml
clientOutput: ./src/api/client.ts
Con apis.<nombre>.clientOutput configurado, un redocly generate-client desnudo genera cada API que haya optado.
--report <archivo> también escribe un archivo JSON con las operaciones de cada API (id, name) y las advertencias de la ejecución, cada una con un kind estable, después de una ejecución exitosa.
client.telemetry: on (solo configuración) hace que el generador typescript también escriba <output>.telemetry.ts (registre use(telemetry({ sdkName, sdkVersion, client }))), y los generadores go, python y php escriben telemetry.go, <module>_telemetry.py y <output>.telemetry.php, para contar llamadas por operación y enviar los conteos una vez por minuto (sin datos de solicitud; REDOCLY_SDK_TELEMETRY=off o DO_NOT_TRACK=1 desactiva el envío).
El bloque client propio de una API reemplaza el de nivel superior por completo; repita los campos compartidos en él.
Con client.codeSamples: true, también escribe <output>.code-samples.yaml, un overlay que añade x-codeSamples; agréguelo a los overlays de la API (o pase --overlay) para que bundle ponga las muestras en la descripción.
Trabajar en un proyecto alojado en Redocly
Después de redocly login, project clone <organización>/<proyecto> clona un proyecto que la plataforma Redocly aloja.
El clon usa Redocly CLI como su ayudante de credenciales Git, por lo que git pull y git push funcionan sin un token.
La plataforma rechaza los envíos a la rama predeterminada: envíe otra rama, luego abra un pull request para ella:
git push -u origin fix-typo
redocly project pr create --title "Corregir un error tipográfico" --body-file - <<'BODY'
Corrige el comando de instalación en el inicio rápido.
BODY
El comando imprime la URL del pull request.
La plataforma construye una vista previa en unos minutos; redocly project pr status muestra entonces el estado, la decisión de revisión, las comprobaciones y la URL de vista previa después de que la vista previa se despliegue.
Probar una API en vivo
respect ejecuta una descripción Arazzo como un conjunto de pruebas contra una API en ejecución, afirmando que las respuestas reales coinciden con la descripción.
Comience desde generate-arazzo <openapi> para esqueleto los flujos de trabajo, luego refine los pasos y criterios de éxito manualmente.
Un paso que omita parameters o requestBody los toma de la descripción del ejemplo de operación.
Capturar tráfico con proxy
proxy inicia un servidor proxy que captura el tráfico HTTP(S) y lo escribe en un archivo HAR. Pase la URL de destino y el puerto:
redocly proxy --destination https://api.example.com --port 8080 --output traffic.har
Use el archivo resultante con drift (para encontrar diferencias con una descripción) o generate-spec (para inferir una nueva descripción).
Obtener estadísticas y puntuación
stats <api> da un recuento de endpoints, esquemas, parámetros y más. score <api> asigna una puntuación de preparación para IA basada en la claridad de la descripción, la cobertura de ejemplos y la consistencia. Ambos admiten --max-problems y --format=json.
Verificar la configuración
check-config valida redocly.yaml mismo. Úselo antes de hacer commit:
redocly check-config
Inspeccionar tipos de nodo
inspect-node-types es útil al escribir reglas de plugin o decoradores personalizados. Pase un archivo de API o un alias:
redocly inspect-node-types my-api
Enviar a la plataforma
push <api> sube la descripción empaquetada a la plataforma Redocly. Requiere autenticación (redocly login). push-status <push-id> rastrea una subida en curso.
Instalar habilidades del agente
skills instala archivos de habilidad del agente en .agents/skills/ y en carpetas de agentes compatibles detectadas. Los agentes compatibles incluyen Cursor, Cline y otros.
Completado del shell
completion genera scripts de autocompletado para bash, zsh, fish y powershell. Redirija la salida a su perfil de shell para habilitarlo de forma permanente.