smart-doc é uma ferramenta que suporta tanto java restful api quanto geração de documentos de interface Apache Dubbo rpc. smart-doc subverte o método de implementação tradicional semelhante ao swagger, que usa muitas anotações para gerar documentos.
smart-doc é completamente baseado na análise do código fonte da interface para gerar documentação da interface, alcançando completamente zero intrusão de anotações, você só precisa escrever de acordo com a anotação padrão java, smart-doc pode ajudá-lo a gerar um markdown simples e claro ou um estilo estático como o documento html do GitBook. Se você está cansado de inúmeras anotações e forte poluição de intrusão de ferramentas de documentação como swagger, por favor, adote o smart-doc!
Características
- Depuração de interface de suporte.
- Anotação zero, custo de aprendizado zero, só precisa escrever anotação java padrão.
- Derivação automática baseada em definições de interface de código fonte, poderosa derivação de estrutura de retorno.
- Suporte Spring MVC, Spring Boot, Spring Boot Web Flux (método de escrita do controlador), especificação JAX-RS.
- Suporta a derivação de interfaces assíncronas como Callable, Future, CompletableFuture, etc.
- Suporte a especificação de verificação de parâmetro JSR303 no JavaBean, suporte à verificação do grupo.
- A interface para parâmetros de solicitação json pode gerar automaticamente parâmetros json simulados.
- Algumas definições de campo comumente usadas podem gerar valores analógicos válidos.
- Suporte para gerar exemplos de valor de retorno json.
- Suporta o carregamento de código-fonte de fora do projeto para gerar anotações de campo (incluindo jars publicados pela especificação padrão).
- Suporte para geração de documentos em vários formatos: Markdown, HTML5, Asciidoctor, coleção Postman, Open Api 3.0+.
- Visualize facilmente a documentação da API HTML5 estática online nos serviços Spring Boot.
- Dados de documentos abertos, acesso gratuito ao sistema de gerenciamento de documentos.
- Uma ferramenta de detecção de comentários de código, amigos que não escrevem comentários não podem escapar do aviso.
- Integração rápida de plug-in (suporta plugins maven e gradle).
- Suporta geração de documentos rpc Apache Dubbo.
- Apoiar a estrutura de desenvolvimento de aplicativos Solon doméstico.
Suporte para Smart-doc e outras ferramentas
| Características | documento inteligente | arrogância |
| hacking de código | Nenhum | A anotação é muito invasiva |
| complexidade de integração | Simples, apenas um plugin | mais complicado |
| Suporte a plug-ins | Existem plugins gradle e maven | Nenhum plug-in |
| suporte à especificação openapi | Suporte openapi 3.0 | Uma versão que suporta totalmente openapi |
| Integração de construção de CI | Disponível nas fases de construção ci comando maven ou gradle Inicie o plugin para gerar documentação
|
não suporta |
| Integração centralizada do centro de documentos | Ele foi conectado com a plataforma de gerenciamento de documentos de interface de nível empresarial torna |
não suporta |
| continuidade de manutenção | É confiável, com uma grande base de usuários após o código aberto, e tem sido continuamente mantido | Existem muitos usuários em todo o mundo e a manutenção de código aberto é confiável |
| depuração de interface | Desde a versão 2.0.0, o debug é suportado e a página é muito mais bonita que o swagger. | Apoio, suporte |
O Smart-doc quase realizou as funções do swagger ui desde 2.0.0, e é mais conciso e elegante do que o swagger ui, e também mais alinhado com as demandas dos desenvolvedores domésticos. A atual funcionalidade smart-doc também foi
Mais do que o swagger fornece para desenvolvedores java. Claro, o próprio smart-doc suporta apenas a digitalização de código para gerar documentos openapi 3.0, e você também pode importar os documentos openapi 3.0 gerados para outra interface do usuário para renderização.
Nos últimos dois anos, muitos desenvolvedores na China desenvolveram plug-ins para gerar documentos de ideias não invasivos, e também continuamos atentos ao desenvolvimento desses plug-ins. Atualmente, a integração desses plug-ins de ideias é definitivamente mais simples que o smart-doc, e a velocidade de geração de documentos é mais rápida que o smart-doc (os plug-ins de ideias não compilam esses estágios), mas atualmente esses plug-ins não resolveram projetos e dependências multimódulos O problema de anotação no cenário não é perfeito para os casos de uso coletados durante o desenvolvimento do smart-doc. Em geral, smart-doc ainda é a melhor ferramenta para desenvolvedores web java domésticos para gerar documentação.
atualizar conteúdo
1. A anotação de validação jsr suporta substituição constante, [#334] ( https://github.com/smart-doc-group/smart-doc/issues/334 ) 2. Use @see para apontar para erros de classe sem enumeração , [ #340] ( https://github.com/smart-doc-group/smart-doc/issues/340 )
efeito de página de depuração
plugin maven ou gradle
oficial do smart-doc Para facilitar aos usuários a integração rápida e não invasiva dos recursos de geração de API de documentação do smart-doc, desenvolvemos plugins maven ou gradle relevantes. Também é recomendado usar o método de plugin para usar o smart-doc.
https://gitee.com/smart-doc-team/smart-doc-maven-plugin
Recomendação oficial
O smart-doc + Torna constitui uma solução de gerenciamento e geração de documentos líder do setor, usando o smart-doc para concluir a análise de código-fonte Java e extrair comentários sem intrusão para gerar documentos de API e enviar documentos automaticamente para a plataforma de gerenciamento de documentos de interface de nível empresarial da Torna.
automação de documentação smart-doc+Torna
O smart-doc tem sido usado para substituir a arrogância em muitas empresas domésticas, e até mesmo os 3 principais fabricantes nacionais têm versões de desenvolvimento secundário do smart-doc. O objetivo futuro de Torna é alcançar e superar Yapi. A capacidade de análise do smart-doc para a pilha de tecnologia java spring é atualmente a mais forte do setor (se você não estiver convencido, use a ferramenta para executar a demonstração de análise do smart-doc). Portanto, a solução smart-doc+Torna é muito poderosa. A Torna está atualmente em um período de iteração de alta velocidade. Bem-vindo à experiência Torna. Nós nos esforçamos para fornecer à comunidade uma solução de documentação de interface eficiente e fácil de usar.
Sugestão de upgrade
smart-doc pode ser atualizado sem problemas com base em versões anteriores. Recomenda-se usar a nova versão
DEMO
Use a demonstração para brincar facilmente com a geração de documentos de interface e exibir os efeitos de outros documentos de caso de usuário: https://api.doubans.com/
usuários conhecidos
- iFlytek
- um mais
- Painço
- ninho de vespas
Em agosto de 2021, o smart-doc também adicionou alguns usuários estrangeiros.