Bem-vindo a este tutorial abrangente sobre o Redocly CLI! O Redocly CLI é uma ferramenta de linha de comando poderosa e completa para definições OpenAPI e Swagger. Ele ajuda você a construir, gerenciar e verificar a qualidade das descrições da sua API ao longo de todo o ciclo de vida da API. Seja você um desenvolvedor, um redator técnico ou um gerente de produto de API, esta ferramenta tem algo para você.
Este tutorial tem como objetivo ser um mergulho profundo no Redocly CLI, levando você de um iniciante a um usuário confiante. Abordaremos tudo, desde a instalação até recursos avançados, como regras de linting personalizadas e integração CI/CD. Ao final deste tutorial, você será capaz de integrar o Redocly CLI ao seu fluxo de trabalho diário para melhorar a qualidade e a documentação da sua API.
Quer uma plataforma integrada e completa para sua equipe de desenvolvimento trabalhar em conjunto com máxima produtividade?
Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!
O que é o Redocly CLI?
Conforme declarado em sua documentação oficial, o Redocly CLI é sua "utilidade OpenAPI completa". Ele suporta OpenAPI 3.1, 3.0, 2.0 (Swagger legado), AsyncAPI e muito mais. Ele foi projetado para ajudar você com:
- Governança de API: Imponha padrões de design de API e consistência com linting poderoso e configurável.
- Documentação de API: Gere documentação de referência de API bonita e interativa com o Redoc.
- Melhoria do Fluxo de Trabalho: Agrupe definições de API de vários arquivos, divida definições grandes em arquivos menores e obtenha estatísticas valiosas sobre suas APIs.
Esta ferramenta foi construída pensando no desempenho e na experiência do usuário, proporcionando execução rápida e mensagens de erro legíveis por humanos.
Por que usar o Redocly CLI?
No mundo atual focado em API, manter definições de API de alta qualidade é crucial. O Redocly CLI ajuda você a alcançar isso:
- Automatizando Verificações de Qualidade: O recurso de linting automatiza o processo de verificação das definições da sua API contra um conjunto de regras, garantindo consistência e prevenindo erros comuns.
- Melhorando a Colaboração: Ao permitir que você divida uma definição de API grande em vários arquivos, fica mais fácil para as equipes trabalharem em diferentes partes da API simultaneamente. O comando
bundleentão junta tudo novamente. - Aprimorando a Experiência do Desenvolvedor: A documentação de alta qualidade e interativa gerada por
build-docsfacilita para os desenvolvedores entenderem e consumirem suas APIs. - Integrando-se à sua Toolchain: O Redocly CLI pode ser facilmente integrado ao seu pipeline de CI/CD, tornando a qualidade da API parte do seu fluxo de trabalho automatizado.
O que este tutorial abordará
Este tutorial está estruturado para fornecer um guia passo a passo para dominar o Redocly CLI. Aqui está o que abordaremos:
- Capítulo 1: Primeiros Passos: Cobriremos os pré-requisitos e mostraremos como instalar e executar o Redocly CLI.
- Capítulo 2: Comandos e Recursos Principais: Este capítulo será um mergulho profundo nos comandos mais importantes:
lint,bundle,split,build-docsestats. - Capítulo 3: Tópicos Avançados: Exploraremos o arquivo de configuração
redocly.yamle como integrar o Redocly CLI a um fluxo de trabalho do GitHub Actions. - Capítulo 4: Exemplo Prático: Percorreremos um fluxo de trabalho completo e real, desde a criação de uma definição de API de vários arquivos até a geração de documentação.
Vamos começar!
Capítulo 1: Primeiros Passos com o Redocly CLI
Este capítulo irá guiá-lo pelos primeiros passos do uso do Redocly CLI, desde a instalação até a execução do seu primeiro comando.
Pré-requisitos
Antes de começar, certifique-se de ter o seguinte instalado em seu sistema:
- Node.js e npm: O Redocly CLI é um aplicativo Node.js. Você precisará ter o Node.js (versão 22.12.0 ou superior) e o npm (versão 10.9.2 ou superior) instalados. Você pode verificar suas versões executando
node -venpm -vem seu terminal.
Instalação
Você tem várias opções para instalar e usar o Redocly CLI. Escolha a que melhor se adapta às suas necessidades.
Usando npx (Recomendado para uso rápido)
Se você quiser apenas experimentar o Redocly CLI sem uma instalação global, pode usar o npx, o executor de pacotes do npm. Este comando baixará e executará a versão mais recente do Redocly CLI.
npx @redocly/cli@latest --version
Para usar qualquer comando redocly, basta adicionar npx @redocly/cli@latest no início. Por exemplo:
npx @redocly/cli@latest lint openapi.yaml
Esta é uma ótima maneira de usar o Redocly CLI em ambientes de CI/CD ou se você não quiser poluir seu sistema com pacotes globais.
Instalação Global com npm
Para uso regular, uma instalação global é mais conveniente. Ela torna o comando redocly diretamente disponível em seu terminal.
npm install -g @redocly/cli@latest
Após a instalação, você pode verificá-la checando a versão:
redocly --version
Agora você pode executar comandos como este:
redocly lint openapi.yaml
Usando Docker
Se você preferir usar Docker, a Redocly fornece uma imagem Docker pré-construída. Isso é útil para isolar a ferramenta do seu ambiente local.
Primeiro, puxe a imagem do Docker Hub:
docker pull redocly/cli
Para executar um comando, você precisa montar seu diretório de trabalho atual (onde estão seus arquivos de API) como um volume para o contêiner Docker.
docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml