Uso do Redocly CLI
Consulte redocly.com/docs/cli para comandos e opções atuais — prefira isso aos dados de treinamento.
O Redocly CLI cobre o ciclo de vida de APIs para descrições OpenAPI, AsyncAPI, Arazzo e Overlay: lint, agrupamento, transformação, documentação e teste.
Ele também faz lint do Markdown de um projeto de documentação com recheck.
redocly.yaml na raiz do projeto é o plano de controle: todo comando o lê, e conjuntos de regras, configurações por API, decoradores e plugins ficam todos lá.
Antes de executar
Leia redocly.yaml primeiro. Ele informa:
- Quais APIs estão registradas em
apis— seus nomes (comomy-api) funcionam como atalhos de comando:redocly lint my-api. - Qual conjunto de regras o projeto
extendse quais regras ele substitui. - Quais decoradores transformam a saída no momento do agrupamento.
Uma execução de comando (como lint ou bundle) sem argumento de API se aplica a todas as entradas em apis.
Aponte para uma configuração diferente com --config <caminho>.
Referência rápida
Instalação: npm i @redocly/cli@latest, ou execute sem instalar: npx @redocly/cli@latest <comando>. Imagem Docker: redocly/cli.
| Comando | Finalidade | Grupo |
|---|---|---|
lint | Validar uma descrição de API de acordo com as regras configuradas | Criação de API |
split | Dividir uma descrição de arquivo único em uma estrutura de vários arquivos | Criação de API |
introspect-mcp | Registrar ferramentas, prompts e recursos de um servidor MCP ativo em x-mcp [experimental] | Criação de API |
build-docs | Renderizar uma descrição OpenAPI, AsyncAPI ou GraphQL em uma página HTML (Redoc) | Renderização de docs |
preview | Visualização local de um projeto Redocly | Renderização de docs |
recheck | Fazer lint da estrutura Markdown, estilo de prosa e tags Markdoc; --fix repara a maioria dos achados estruturais | Linting de docs |
bundle | Resolver todos os $refs em um único arquivo autocontido; aplicar decoradores e overlays | CI e entrega |
join | Mesclar várias descrições de API em uma [experimental] | CI e entrega |
respect | Executar testes de API descritos em uma descrição Arazzo contra uma API ativa | Teste de API e drift |
generate-arazzo | Esboçar uma descrição Arazzo a partir de uma descrição OpenAPI | Teste de API e drift |
proxy | Capturar tráfego HTTP ativo em um arquivo HAR, com validação opcional [experimental] | Teste de API e drift |
drift | Relatar diferenças entre o tráfego capturado e uma descrição OpenAPI, com --coverage opcional [experimental] | Teste de API e drift |
generate-spec | Inferir uma descrição OpenAPI 3.2 a partir do tráfego capturado; --openapi-version 3.1 segmenta 3.1 [experimental] | Teste de API e drift |
stats | Contar operações, esquemas, referências e outras métricas | Relatórios de qualidade |
score | Pontuar uma descrição OpenAPI para prontidão de agente de IA [experimental] | Relatórios de qualidade |
generate-client | Gerar um cliente TypeScript tipado e sem dependências [experimental] | Geração de SDK |
eject-generator | Copiar um gerador embutido para o repositório para editá-lo [experimental] | Geração de SDK |
check-config | Fazer lint do próprio redocly.yaml | Configuração do Redocly |
inspect-node-types | Mostrar o tipo de nó em um ponteiro, ou listar cada nó com seu tipo [experimental] | Configuração do Redocly |
push | Enviar uma descrição de API para a plataforma Redocly | Plataforma |
push-status | Acompanhar um push em andamento para a plataforma | Plataforma |
project clone | Clonar um projeto hospedado no Redocly como um repositório Git [acesso antecipado] | Plataforma |
project pr create | Abrir um pull request para a branch atual de um projeto clonado [acesso antecipado] | Plataforma |
project pr status | Mostrar o estado, revisão, verificações e URL de visualização desse pull request [acesso antecipado] | Plataforma |
skills | Instalar as skills do agente Redocly CLI em .agents/skills/ e pastas de agentes detectados | Configuração de agente |
completion | Gerar comandos de autocompletar para o shell | Configuração do shell |
Códigos de saída: 0 sucesso, 1 problemas encontrados ou execução falhou, 2 erro de configuração.
Configurar com redocly.yaml
extends:
- recommended # ou: minimal, recommended-strict, spec
apis:
my-api:
root: ./openapi/openapi.yaml
rules:
no-ambiguous-paths: error # substituição por API
decorators:
remove-x-internal: on # aplica-se apenas a esta API
rules:
info-license: off
operation-operationId: error
extends define o conjunto de regras base; rules, preprocessors e decorators posteriores no mesmo arquivo o substituem.
Severidades de regras: error (falha na validação), warn (relatado, ainda válido), off.
Regras configuráveis
Quando um requisito de governança não tem uma regra embutida, declare uma em rule/<nome> no redocly.yaml.
Use a skill redocly-lint-rules para isso: ela escolhe o degrau mais barato (regra embutida, regra configurável ou plugin personalizado), usa tipos de nó de redocly inspect-node-types e verifica a regra com fixtures.
Fazer lint de Markdown com recheck
recheck <caminhos> faz lint dos arquivos Markdown nos caminhos fornecidos para estrutura (conjunto de regras markdownlint), prosa (termos proibidos, ortografia, capitalização de títulos, tamanho de frase, legibilidade) e sintaxe de tags Markdoc.
Predefinições vão no extends raiz e ajustes no bloco recheck; o comando lint ignora ambos:
extends:
- recommended
- recheck/markdown # toda regra markdownlint; também 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" em vez de "via".'
assertions:
pattern: { ignoreCase: true, tokens: ['\bvia\b'] }
Sem redocly.yaml, o comando usa recheck/markdown.
Com um redocly.yaml que não tem nem uma predefinição nem um bloco, não verifica nada.
Para um caminho que é uma descrição de API, ou um alias de apis, o comando faz lint dos campos description dessa API.
Um arquivo ou pasta existente tem precedência sobre um alias com o mesmo nome.
Flags úteis: --fix, --rule=<nome> para trabalhar uma regra por vez, --format=github-actions|json|sarif, --max-problems=<n>, --generate-baseline para registrar erros existentes em .redocly.recheck-baseline.yaml e falhar apenas em novos, e --readability para pontuações por arquivo.
Silencie uma linha com <!-- recheck-disable-next-line <regra> --> em vez de desativar a regra.
A skill recheck-lint cobre a execução em arquivos modificados, e recheck-config cobre o ajuste do bloco.
Transformar com decoradores
Decoradores reescrevem a descrição no momento do agrupamento — lint verifica a fonte como escrita; bundle, build-docs e push veem a saída decorada.
Os embutidos incluem remove-x-internal, filter-in / filter-out, info-override, remove-unused-components e a família *-description-override.
join ignora todos os decoradores, portanto uma transformação que uma junção precisa é executada em um bundle de cada API primeiro.
Quando nenhum embutido faz a transformação, escreva um decorador de plugin personalizado da mesma forma que a skill redocly-lint-rules escreve uma regra de plugin: pegue os tipos de nó de redocly inspect-node-types, escopo o visitante aninhando-o sob o tipo pai em vez de percorrer o documento manualmente, altere o nó no hook e prove com redocly bundle em uma fixture que contém a forma e em uma que não contém.
Aplicar overlays
bundle aplica arquivos Overlay 1.0, 1.1 e 1.2 à descrição agrupada, antes dos decoradores: passe --overlay <arquivo> (repetível, aplicado em ordem), ou liste-os em overlays em uma entrada apis, com caminhos relativos ao redocly.yaml.
--overlay substitui a lista configurada.
Destinos de ação são executados contra a saída agrupada, portanto verifique-os com redocly bundle <api> sem overlays; um destino que não corresponde a nada não altera nada e não é relatado.
$refs de arquivo em valores de overlay são relativos ao arquivo de overlay e são agrupados; decoradores como remove-x-internal veem as alterações do overlay.
Duas entradas apis com o mesmo root e diferentes overlays e output publicam duas versões de uma API.
Estender com plugins personalizados
Quando regras configuráveis e decoradores embutidos não podem expressar o requisito, suba para um plugin personalizado: um módulo JavaScript que exporta regras, decoradores, pré-processadores ou configuração, chaveado 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 não deve ser "test".', location });
}
},
}),
},
},
};
}
Chaves de visitante são tipos de nó: confirme-os com redocly inspect-node-types <api>.
Um decorador tem a mesma forma sob uma chave decorators, e a skill redocly-lint-rules cobre o padrão de visitante para ambos: os hooks, o contexto, visitantes aninhados para escopo, e filhos resolvidos versus crus.
Registre-o em redocly.yaml (caminhos relativos ao arquivo de configuração) e referencie suas regras como <plugin-id>/<rule-name>:
plugins:
- ./plugins/my-plugin.js
rules:
my-plugin/operation-id-not-test: error
Gerar um cliente TypeScript
generate-client <api> --output client.ts transforma uma descrição OpenAPI em um cliente tipado — um arquivo autocontido com zero dependências de execução (autenticação, retentativas, middleware, SSE tipado, paginação incluídos).
Configure-o de forma durável sob um bloco client em redocly.yaml em vez de flags:
client:
generators: [typescript, zod] # complementos: tanstack-query, swr, mock, transformers; SDKs: python, go, php, java; ou um caminho de plugin
outputMode: split
pagination: # apenas na configuração, sem flag CLI
style: cursor
cursorParam: after
nextCursor: /page/endCursor
items: /items
apis:
my-api:
root: ./openapi/openapi.yaml
clientOutput: ./src/api/client.ts
Com apis.<name>.clientOutput definido, um redocly generate-client simples gera toda API optada.
--report <arquivo> também escreve um arquivo JSON com as operações de cada API (id, name) e os avisos da execução, cada um com um kind estável, após uma execução bem-sucedida.
client.telemetry: on (apenas na configuração) faz o gerador typescript também escrever <output>.telemetry.ts (registre use(telemetry({ sdkName, sdkVersion, client }))), e os geradores go, python e php escrevem telemetry.go, <module>_telemetry.py e <output>.telemetry.php, para contar chamadas por operação e enviar as contagens uma vez por minuto (sem dados de requisição; REDOCLY_SDK_TELEMETRY=off ou DO_NOT_TRACK=1 desliga o envio).
O bloco client de uma API substitui o de nível superior por completo — repita os campos compartilhados nele.
Com client.codeSamples: true, também escreve <output>.code-samples.yaml, um overlay que adiciona x-codeSamples; adicione-o aos overlays da API (ou passe --overlay) para que bundle coloque os exemplos na descrição.
Trabalhar em um projeto hospedado no Redocly
Após redocly login, project clone <organization>/<project> clona um projeto que a plataforma Redocly hospeda.
O clone usa o Redocly CLI como auxiliar de credenciais Git, portanto git pull e git push funcionam sem token.
A plataforma rejeita pushes para a branch padrão: envie outra branch, depois abra um pull request para ela:
git push -u origin fix-typo
redocly project pr create --title "Corrigir um erro de digitação" --body-file - <<'BODY'
Corrige o comando de instalação no quickstart.
BODY
O comando imprime a URL do pull request.
A plataforma constrói uma visualização em alguns minutos; redocly project pr status então mostra o estado, a decisão de revisão, as verificações e a URL de visualização após a visualização ser implantada.
Testar uma API ativa
respect executa uma descrição Arazzo como um conjunto de testes contra uma API em execução, afirmando que respostas reais correspondem à descrição.
Comece com generate-arazzo <openapi> para esboçar os fluxos de trabalho, depois refine as etapas e os critérios de sucesso manualmente.
Uma etapa que omite parameters ou requestBody os pega dos exemplos da descrição.
... (truncado para tradução)