Como baixar e usar o Redoc para documentação da API
Se você está procurando uma maneira simples e poderosa de criar documentação de API interativa a partir de suas especificações OpenAPI, talvez queira conferir o Redoc. Redoc é uma ferramenta de código aberto que gera documentação de API a partir de definições de OpenAPI (fka Swagger). Por padrão, o Redoc oferece um layout responsivo de três painéis: o painel esquerdo contém uma barra de pesquisa e um menu de navegação. O painel central contém a documentação. O painel direito contém exemplos de solicitação e resposta.
Neste artigo, mostrarei como baixar e usar o Redoc para criar belos documentos de API em minutos. Também abordarei algumas das opções de personalização e recursos que destacam o Redoc entre outras ferramentas de documentação. Por fim, compararei o Redoc com algumas das alternativas disponíveis para gerar documentos de API a partir das especificações do OpenAPI.
download redoc
Como instalar o Redoc
A instalação do Redoc é muito fácil. Na verdade, existem quatro maneiras diferentes de implantar a ferramenta, dependendo de suas preferências e necessidades. Aqui estão as etapas para cada método:
Instale o Redoc via npm ou yarn
Se estiver usando npm ou yarn como gerenciador de pacotes, você pode instalar o Redoc como uma dependência em seu projeto. Basta executar o seguinte comando no seu terminal:
npm install redoc --save # ou yarn add redoc
Isso fará o download da versão mais recente do Redoc e a adicionará ao seu arquivo package.json.
Faça referência ao JS em HTML localmente ou via CDN
Se você não quiser usar um gerenciador de pacotes, basta fazer referência ao arquivo JavaScript para Redoc em sua página HTML. Você pode hospedar o arquivo sozinho ou usar um CDN público. Por exemplo, você pode adicionar a seguinte tag de script à sua página HTML:
<script src="
Isso carregará a versão mais recente do Redoc do jsDelivr CDN.
Use o componente Redoc React
Se você estiver usando o React como sua estrutura de front-end, poderá usar o componente Redoc React para renderizar a documentação da API.Primeiro, você precisa instalar o pacote redoc-react:
npm install redoc-react --save # ou yarn add redoc-react
Em seguida, você pode importar o componente e usá-lo em seu código JSX:
importar Reagir de 'reagir'; importar RedocStandalone de 'redoc-react'; class App extends React.Component render() return ( );
Isso renderizará a documentação da API usando a especificação de exemplo petstore.
Instalar o Redoc via Docker
Se preferir usar o Docker, você também pode instalar o Redoc como uma imagem do Docker. Primeiro, você precisa extrair a imagem do Docker Hub:
docker pull redocly/redoc
Em seguida, você pode executar a imagem com sua URL de especificação OpenAPI como uma variável de ambiente:
docker run -it --rm -p 8080:80 -e SPEC_URL=' redocly/redoc
Isso iniciará um servidor da Web na porta 8080 e exibirá sua documentação de API usando a especificação de exemplo petstore.
Como usar o Redoc
Depois de instalar o Redoc, usá-lo é muito simples. Tudo o que você precisa é de um arquivo de especificação OpenAPI válido no formato JSON ou YAML. Você pode usar um arquivo existente ou criar um do zero usando uma ferramenta como [OpenAPI GUI](^6^) ou [Swagger Editor](^7^). Você também pode usar [Redocly Workflows](^8^) para criar e gerenciar suas definições OpenAPI de forma colaborativa.
Para usar o Redoc, você só precisa passar a URL do seu arquivo de especificação OpenAPI para o specUrl atributo do <redoc> elemento em sua página HTML. Por exemplo:
<redoc spec-url="
Isso renderizará a documentação da API usando a especificação de exemplo petstore. Você também pode usar um caminho relativo para seu arquivo de especificação se hospedá-lo no mesmo servidor que sua página HTML.
Se você quiser usar o componente React, você precisa passar a URL do seu arquivo de especificação OpenAPI para o specUrl adereço do <RedocStandalone> componente em seu código JSX. Por exemplo:
<RedocStandalone specUrl=" />
Isso também renderizará a documentação da API usando a especificação de exemplo petstore.
Se quiser usar a imagem do Docker, você precisa passar a URL do seu arquivo de especificação OpenAPI como uma variável de ambiente para o docker run comando. Por exemplo:
docker run -it --rm -p 8080:80 -e SPEC_URL=' redocly/redoc
Isso iniciará um servidor da web na porta 8080 e servirá sua documentação de API usando a especificação de exemplo petstore também.
Como personalizar o Redoc
Uma das vantagens do Redoc é que ele permite personalizar a aparência e o comportamento da documentação da API. Você pode usar várias opções e extensões para ajustar o layout, cores, fontes, menus, amostras e muito mais. Aqui estão algumas das opções de personalização que o Redoc oferece:
Opções de temas
Para personalizar o estilo da documentação da API, você pode usar o tema opção em sua página HTML ou código JSX. Essa opção usa um objeto com várias propriedades que controlam as cores, fontes, pontos de interrupção e blocos de código de sua documentação. Por exemplo:
<redoc spec-url=" theme="colors: primary: main: '#dd3333'"></redoc>
Isso mudará a cor primária da sua documentação para vermelho. Você pode encontrar uma lista completa de opções de temas na [documentação do Redoc](^9^).
extensão x-tagGroups
Para agrupar suas tags em categorias de alto nível no menu lateral, você pode usar o x-tagGroups extensão em seu arquivo de especificação OpenAPI. Esta extensão leva uma matriz de objetos com nome e Tag propriedades. Por exemplo:
x-tagGroups: - name: Pets tags: - pet - store - name: Users tags: - user
Isso criará dois grupos no menu lateral: Animais de estimação e Usuários, cada um contendo as tags correspondentes.
extensão do logotipo x
Para exibir o logotipo da sua marca no cabeçalho da documentação, você pode usar o logotipo x extensão em seu arquivo de especificação OpenAPI. Esta extensão pega um objeto com várias propriedades que controlam a imagem do logotipo, URL, cor de fundo e texto alternativo. Por exemplo:
x-logo: url: " backgroundColor: "#FFFFFF" altText: "Example logo" href: "
Isso exibirá uma imagem de logotipo vinculada ao seu site.
extensão x-codeSamples
Para adicionar exemplos de código personalizados para diferentes linguagens e estruturas, você pode usar o x-codeSamples extensão em seu arquivo de especificação OpenAPI. Esta extensão leva uma matriz de objetos com idioma e fonte propriedades . Por exemplo:
x-codeSamples: - lang: fonte "JavaScript": const axios = require('axios'); axios.get(' .then(response => console.log(response.data)) .catch(error => console.error(error)); - lang: "Python" fonte: importar solicitações response = requests.get(' print(response.json())
Isso exibirá dois exemplos de código para JavaScript e Python no painel direito da sua documentação.
extensão x-exemplos
Para adicionar exemplos personalizados para seus corpos de solicitação e resposta, você pode usar o x-exemplos extensão em seu arquivo de especificação OpenAPI. Esta extensão pega um objeto com resumo e valor propriedades. Por exemplo:
x-examples: application/json: summary: "A simple pet" value: id: 1 name: "Fluffy" category: "cat"
Isso exibirá um exemplo de animal de estimação simples no formato JSON no painel direito da sua documentação.
Quais são os recursos e benefícios do Redoc
Redoc não é apenas uma ferramenta para gerar documentação de API. É também uma ferramenta para aprimorar a experiência do usuário e a compreensão de sua API. O Redoc oferece muitos recursos e benefícios que o tornam uma ótima opção para documentar sua API. Aqui estão alguns deles:
Layout interativo e responsivo
O Redoc fornece um layout de três painéis que se adapta a diferentes tamanhos de tela e dispositivos. O painel esquerdo contém uma barra de pesquisa e um menu de navegação que permite pular rapidamente para diferentes seções de sua documentação. O painel central contém a documentação propriamente dita, com descrições, parâmetros, esquemas e respostas claros e concisos.O painel direito contém exemplos interativos que mostram como fazer solicitações e o que esperar em troca. Você também pode expandir e recolher os painéis conforme desejar.
Suporte para OpenAPI 3.0 e 2.0
O Redoc oferece suporte às especificações OpenAPI 3.0 e 2.0, que são os padrões mais usados para descrever APIs RESTful. Você pode usar o Redoc para documentar qualquer API que siga essas especificações, independentemente da linguagem de programação ou estrutura que você usa. O Redoc também suporta vários recursos do OpenAPI 3.0, como callbacks, links, oneOf, anyOf, allOf, discriminador, etc.
Opções de personalização e temas
O Redoc permite personalizar a aparência e o comportamento da documentação da API usando várias opções e extensões. Você pode alterar as cores, fontes, pontos de interrupção, blocos de código, menus, amostras e muito mais usando o tema opção ou variáveis CSS. Você também pode agrupar suas tags em categorias, exibir seu logotipo, adicionar amostras de código personalizado, exemplos e muito mais usando o x-tagGroups, logotipo x, x-codeSamples, x-exemplos, e outras extensões.
Sem dependências do lado do servidor ou etapas de compilação
O Redoc é uma ferramenta autônoma que não requer nenhuma dependência do lado do servidor ou etapas de construção. Você pode simplesmente fazer referência ao arquivo JavaScript para Redoc em sua página HTML ou usar o componente React ou a imagem do Docker para implantá-lo. O Redoc renderizará a documentação da API instantaneamente a partir do arquivo de especificação OpenAPI sem nenhuma configuração ou processamento adicional.
Código aberto e gratuito
Redoc é um projeto de código aberto licenciado sob a licença MIT. Isso significa que você pode usá-lo gratuitamente para qualquer finalidade, modificá-lo como desejar e contribuir para seu desenvolvimento e aprimoramento. Você também pode acessar o código-fonte, a documentação, os problemas e as solicitações pull no [GitHub].
Quais são algumas alternativas para Redoc
Redoc não é a única ferramenta para gerar documentação de API a partir de especificações OpenAPI.Existem muitas outras ferramentas que oferecem recursos e capacidades semelhantes ou diferentes. Aqui estão algumas das alternativas que você pode querer considerar:
Nome
Descrição
Prós
Contras
[IU do Swagger]
Uma ferramenta popular para visualizar e testar APIs de especificações OpenAPI.
- Suporta OpenAPI 3.0 e 2.0- Fornece recursos de teste interativos- Permite customização via plugins e temas- Amplamente utilizado e suportado por Swagger UI
Swagger UI é uma ferramenta popular para visualizar e testar APIs de especificações OpenAPI. Ele fornece uma interface baseada na web que permite explorar os endpoints, parâmetros, respostas e exemplos de sua API. Você também pode usar o Swagger UI para fazer solicitações ao vivo e ver os resultados em tempo real.
Alguns dos profissionais do Swagger UI são:
Ele oferece suporte às especificações OpenAPI 3.0 e 2.0.
Ele fornece recursos de teste interativos que permitem que você experimente sua API sem escrever nenhum código.
Ele permite a personalização por meio de plug-ins e temas que permitem alterar a aparência de sua documentação.
É amplamente utilizado e suportado pela comunidade e possui muitas integrações com outras ferramentas e plataformas.
Alguns dos contras do Swagger UI são:
Pode ser lento e volumoso para APIs grandes ou complexas.
Ele não oferece muito controle sobre o layout e a estrutura de sua documentação.
Pode ser confuso para iniciantes ou usuários não técnicos que não estão familiarizados com a sintaxe OpenAPI.
Ele não oferece suporte a alguns dos recursos avançados do OpenAPI 3.0, como retornos de chamada, links, oneOf, anyOf, allOf, discriminador etc.
Slate API Docs Generator
Slate API Docs Generator é uma ferramenta gratuita e de código aberto para gerar documentação de API a partir de arquivos Markdown. Ele produz páginas HTML estáticas que são fáceis de hospedar e compartilhar. Slate API Docs Generator oferece um design limpo e elegante que se concentra na legibilidade e usabilidade.
Algumas das vantagens do Slate API Docs Generator são:
É gratuito e de código aberto, o que significa que você pode usá-lo para qualquer finalidade, modificá-lo como desejar e contribuir para seu desenvolvimento e aprimoramento.
Ele usa Markdown como formato de origem, que é uma linguagem de marcação simples e amplamente usada, fácil de escrever e ler.
Ele produz páginas HTML estáticas que são rápidas, seguras e compatíveis com SEO.
Ele oferece suporte a vários idiomas e estruturas para amostras de código usando [Rouge], um marcador de sintaxe baseado em Ruby.
Alguns dos contras do Slate API Docs Generator são:
Ele não suporta especificações OpenAPI nativamente, o que significa que você deve escrever sua documentação manualmente ou usar uma ferramenta de conversão como [Widdershins].
Ele não fornece recursos de teste interativos ou exemplos ao vivo que permitem que você experimente sua API.
Não oferece muita personalização ou opções de temas além de alterar as cores e fontes.
Pode ser difícil manter ou atualizar sua documentação à medida que sua API evolui ou muda.
Conclusão
Neste artigo, mostrei como baixar e usar o Redoc para criar documentação de API interativa a partir de suas especificações OpenAPI. Também abordei algumas das opções de personalização e recursos que destacam o Redoc entre outras ferramentas de documentação. Por fim, comparei o Redoc com algumas das alternativas disponíveis para gerar documentos de API a partir das especificações do OpenAPI.
Se você está procurando uma maneira simples e poderosa de documentar sua API, recomendo que experimente o Redoc. Redoc é uma ferramenta de código aberto que gera documentação de API a partir de definições de OpenAPI (fka Swagger). Por padrão, o Redoc oferece um layout responsivo de três painéis: o painel esquerdo contém uma barra de pesquisa e um menu de navegação. O painel central contém a documentação. O painel direito contém exemplos de solicitação e resposta. Você também pode personalizar a aparência e o comportamento do Redoc usando várias opções e extensões.
Para começar a usar o Redoc, você só precisa de um arquivo de especificação OpenAPI válido no formato JSON ou YAML.Você pode usar um arquivo existente ou criar um do zero usando uma ferramenta como [OpenAPI GUI](^6^) ou [Swagger Editor]. Você também pode usar [Redocly Workflows] para criar e gerenciar suas definições OpenAPI de forma colaborativa. Em seguida, você pode instalar o Redoc via npm, yarn, CDN, componente React ou imagem do Docker. Por fim, você pode usar o Redoc para renderizar a documentação da API dinamicamente a partir do arquivo de especificações da OpenAPI sem nenhuma configuração ou processamento adicional.
perguntas frequentes
O que é OpenAPI?
OpenAPI é um padrão para descrever APIs RESTful de forma legível por máquina e legível por humanos. Ele permite que você defina os endpoints, parâmetros, respostas, esquemas de segurança e outros detalhes de sua API em um arquivo JSON ou YAML. Você pode usar OpenAPI para gerar documentação, ferramentas de teste, cliente [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message) [assistant](#message ) [assistant](#message) sdk e stubs de servidor do seu arquivo de especificação OpenAPI.
O que é Redocly?
A Redocly é uma empresa que fornece um conjunto de ferramentas e serviços para trabalhar com especificações OpenAPI. A Redocly oferece três produtos principais: Redocly, Redocly Workflows e Redocly API Registry. Redoc é a ferramenta que discuti neste artigo. Redocly Workflows é uma plataforma baseada em nuvem que ajuda você a criar, gerenciar e colaborar em suas definições de OpenAPI. Redocly API Registry é um hub centralizado que ajuda você a descobrir, explorar e consumir APIs de várias fontes.
Como posso contribuir com o Redoc?
Redoc é um projeto de código aberto que recebe contribuições da comunidade. Se você deseja contribuir com o Redoc, pode fazê-lo relatando problemas, sugerindo recursos, enviando solicitações de pull, escrevendo documentação ou divulgando. Você pode encontrar mais informações sobre como contribuir no [repositório GitHub do Redoc].
Como posso obter suporte para Redoc?
Se você precisar de suporte para o Redoc, poderá usar um dos seguintes canais:
Leia a [documentação oficial] do Redoc.
Junte-se ao [bate-papo da comunidade Redoc] no Gitter.
Faça uma pergunta sobre [Stack Overflow] usando o redoc marcação.
Entre em contato com a [equipe de suporte do Redocly] por e-mail ou chat.
Como posso saber mais sobre o Redoc?
Se quiser saber mais sobre o Redoc, você pode usar um dos seguintes recursos:
Assista ao [vídeo de demonstração do Redoc] no YouTube.
Leia o [blog Redoc] para atualizações e dicas.
Siga [Redoc no Twitter] para notícias e anúncios.
Confira alguns [exemplos de Redoc em ação] na web.
Espero que você tenha gostado deste artigo e aprendido algo novo sobre o Redoc. Se sim, compartilhe com seus amigos e colegas que possam estar interessados na documentação da API. E se você tiver quaisquer comentários ou perguntas, por favor, deixe um comentário abaixo. Obrigado por ler!
: .com/article/2336385-korean-nuclear-fusion-reactor-achieves-100-millionc-for-30-seconds/: : : [documentação oficial]: [bate-papo da comunidade Redoc]: [Stack Overflow]: [equipe de suporte do Redocly]: /contact-us/ [Redoc demo video]: [Redoc blog]: [Redoc no Twitter]: [exemplos de Redoc em ação]: 0517a86e26
Comments