Docusaurus é um gerador de sites estáticos de código aberto desenvolvido pelo Facebook. É principalmente usado para construir documentação técnica e referências de API. No entanto, Docusaurus não é uma ferramenta dedicada de documentação de API, e existem alguns desafios associados a ele. Neste artigo, vamos apresentá-lo a uma maneira fácil de migrar seus arquivos Markdown ou páginas web construídas do Docusaurus para Apidog.
Venha experimentar a interface do usuário simples e intuitiva do Apidog clicando no botão abaixo!
Sobre o Docusaurus
Docusaurus é um gerador de sites estáticos de código aberto desenvolvido pelo Facebook. É principalmente usado para construir documentação técnica e referências de API. O Docusaurus é totalmente compatível com o formato Markdown, permitindo que você converta automaticamente documentos escritos em Markdown em páginas web.
Desafios na Criação de Documentação de API
Embora o Docusaurus seja geralmente adequado para criar documentação de API, não é uma ferramenta dedicada de documentação de API, e existem alguns desafios:
- Falta de especialização em referência de API
Como uma ferramenta de documentação técnica de propósito geral, o Docusaurus pode não ter recursos específicos para referências de API (como definições de parâmetros, destaque de exemplos de requisição/resposta, etc.). - Sem integração com especificações de API
O Docusaurus não possui a capacidade de gerar documentação automaticamente com base nas especificações de API, então você precisa escrever tudo manualmente. Ele não pode se integrar com o desenvolvimento orientado por especificações como o OpenAPI. - Desafios na gestão de versões
Se os caminhos ou parâmetros de recursos da API mudarem com uma atualização de versão, pode ser difícil acompanhar apenas com o Docusaurus. - Ecosistema de plugins imaturo
Ainda não existem plugins suficientes dedicados à documentação de API, o que pode tornar a personalização desafiadora.
Como resultado, o Docusaurus pode ser muito geral em comparação com ferramentas dedicadas à criação de documentação de API. Para aqueles que buscam uma alternativa ao Docusaurus, recomendamos o Apidog, uma ferramenta que é totalmente compatível com o formato Markdown e também suporta a geração de documentação de API intuitiva e limpa a partir de especificações de API. O Apidog é a opção mais adequada para aqueles que desejam criar referências de API.
Migrando Arquivos do Docusaurus para Apidog
Neste artigo, vamos apresentar uma solução para migrar seus arquivos do Docusaurus para o Apidog para construir uma referência de API mais abrangente.
O Apidog suporta várias sintaxes Markdown e pode converter automaticamente arquivos Markdown em páginas web, assim como o Docusaurus. Além disso, o Apidog pode gerar documentação limpa de arquivos de especificação de API, permitindo que você liste páginas web Markdown e páginas de documentação de API juntas.
botão
A migração do Docusaurus para o Apidog pode ser altamente benéfica, pois permite uma criação e gerenciamento mais apropriados da documentação de API.
Requisitos de Migração
Para migrar seus arquivos do Docusaurus para o Apidog, você precisará do seguinte:
- Uma conta no Apidog: Se você não tem uma, cadastre-se no Apidog agora.
- Os arquivos Markdown originais do seu site: Estes geralmente estão armazenados nas pastas
docs/oublog/do seu projeto.
1. Criar um Projeto HTTP no Apidog
Criar um projeto HTTP no Apidog.
2. Migrar Arquivos Markdown do Docusaurus para o Apidog
Após criar o projeto HTTP, vá até o menu à esquerda, selecione "Configurações" → "Importar Dados", e escolha "Markdown." Aqui, você pode importar seus arquivos Markdown do Docusaurus.
- Ao importar arquivos Markdown para o Apidog, você pode definir os nomes dos arquivos você mesmo. Você pode importar os arquivos Markdown sem alterar os nomes ou definir a primeira linha do conteúdo do arquivo como o nome do arquivo.
3. Editar Arquivos Markdown
Após importar seus arquivos Markdown com sucesso, você pode facilmente editá-los no Apidog.
- Diferente do Docusaurus, o Apidog também suporta a criação de documentação de API. Você pode facilmente gerar páginas de documentação a partir de arquivos de especificação de API e listar documentos de API juntamente com seus arquivos Markdown.
4. Publicar o Projeto
Depois de terminar a edição, você pode publicar seu projeto. Vá ao menu à esquerda, selecione "Compartilhar" → "Configurações de Publicação" para publicar seu projeto.
- Usando um Domínio Personalizado: Com o Apidog, você pode implantar seu projeto em seu próprio domínio. Clique no botão "Editar" para "Domínio Personalizado", verifique sua propriedade do domínio, e você poderá implantar este projeto no domínio especificado.
5. Verificar o Projeto Migrado
Após publicar seu projeto no Apidog, você pode acessá-lo pelo domínio que especificou para visualizar a página do projeto. Todos os seus arquivos Markdown serão automaticamente convertidos em páginas web, e suas especificações de API serão automaticamente convertidas em páginas de documentação.
Resumo
Neste artigo, explicamos em detalhes os passos para migrar arquivos do Docusaurus para o Apidog.
Embora o Docusaurus seja adequado para criar documentação de API, ele apresenta alguns desafios. Por outro lado, o Apidog suporta totalmente Markdown e oferece recursos voltados para a criação de documentação de API, como geração automática de documentação a partir de especificações de API. O Apidog permite que você importe diretamente arquivos Markdown do Docusaurus, tornando-se uma ferramenta que possibilita uma criação e gerenciamento suaves de referências de API. Recomendamos que você consulte os passos descritos neste artigo para migrar seus ativos do Docusaurus para o Apidog.
Ao migrar para o Apidog, você pode esperar os seguintes benefícios:
- Gerenciamento centralizado de documentação Markdown e de API
- Eficiência melhorada através de uma abordagem orientada por especificações de API
- Recursos robustos de controle de versão e personalização
- Capacidade de publicação em domínios personalizados
- Alcançar tanto a melhoria da qualidade quanto a manutenibilidade da documentação de API
O Apidog é uma opção poderosa quando você pretende equilibrar a qualidade e a manutenibilidade da sua documentação de API. Esperamos que este artigo ajude você no processo de migração.
