smart-doc is a tool that supports both java restful api and Apache Dubbo rpc interface document generation. smart-doc subverts the traditional implementation method similar to swagger, which uses a lot of annotations to generate documents.
smart-doc is completely based on the analysis of interface source code to generate interface documentation, completely achieving zero intrusion of annotations, you only need to write according to java standard annotations, smart-doc can help you generate a simple and clear markdown or a static style like GitBook html document. If you are tired of countless annotations and strong intrusion pollution of documentation tools such as swagger, please embrace smart-doc!
Features
- Support interface debugging.
- Zero annotation, zero learning cost, only need to write standard java annotation.
- Automatic derivation based on source code interface definitions, powerful return structure derivation.
- Support Spring MVC, Spring Boot, Spring Boot Web Flux (controller writing method), JAX-RS specification.
- Supports the derivation of asynchronous interfaces such as Callable, Future, CompletableFuture, etc.
- Support JSR303 parameter verification specification on JavaBean, support group verification.
- The interface for json request parameters can automatically generate mock json parameters.
- Some commonly used field definitions can generate valid analog values.
- Support for generating json return value examples.
- Supports loading source code from outside the project to generate field annotations (including jars published by the standard specification).
- Support for generating documents in multiple formats: Markdown, HTML5, Asciidoctor, Postman collection, Open Api 3.0+.
- Easily view static HTML5 api documentation online on Spring Boot services.
- Open document data, free access to document management system.
- A code comment detection tool, friends who don't write comments can't escape the notice.
- Plug-in fast integration (supports maven and gradle plugins).
- Support Apache Dubbo rpc document generation.
- Support domestic Solon Web framework.
Support for Smart-doc and other tools
| Features | smart-doc | swagger |
| code hacking | none | Annotation is very invasive |
| integration complexity | Simple, just a plugin | more complicated |
| Plugin support | There are gradle and maven plugins | No plugins |
| openapi specification support | Support openapi 3.0 | A version that fully supports openapi |
| CI build integration | Available in the ci build phase maven or gradle command Start the plugin to generate documentation
|
not support |
| Centralized document center integration | It has been connected with the torna enterprise-level interface document management platform |
not support |
| maintenance continuity | It is trustworthy, with a large user base after open source, and has been continuously maintained | There are many users around the world, and open source maintenance is trustworthy |
| interface debug | Since version 2.0.0, debug has been supported, and the page is much more beautiful than swagger. | support |
Smart-doc has almost realized the functions of swagger ui since 2.0.0, and is more concise and elegant than swagger ui, and also more in line with the demands of domestic developers. Of course, the function of smart-doc has also been
More than what swagger provides for java developers. Of course, smart-doc itself only supports scanning code to generate openapi 3.0 documents, and you can also import the generated openapi 3.0 documents into other ui for rendering and display.
update content
1. Modify the problem of incomplete automatic analysis of static constants in 2.4.1.
2. Added header automatic constant parsing.
3. Modify the problem of generic inheritance parsing in some special cases https://github.com/smart-doc-group/smart-doc/issues/215
4. Optimize the handling of special greater than and less than symbols in the document.
debug page effect
maven or gradle plugin
smart-doc official In order to facilitate users to quickly and non-invasively integrate smart-doc's documentation api generation capabilities, we develop relevant maven or gradle plugins. It is also recommended to use the plugin method to use smart-doc.
https://gitee.com/smart-doc-team/smart-doc-maven-plugin
Official Recommendation
smart-doc + Torna form an industry-leading document generation and management solution. Smart-doc is used to non-invasively complete Java source code analysis and extract comments to generate API documents, and automatically push documents to Torna's enterprise-level interface document management platform.
smart-doc+Torna documentation automation
smart-doc has been used to replace swagger in many domestic enterprises, and even the top 3 domestic manufacturers have secondary development versions of smart-doc. Torna's future goal is to catch up and surpass Yapi. The parsing ability of smart-doc for the java spring technology stack is currently the strongest in the industry (if you are not convinced, use the tool to run the parsing demo of smart-doc). Therefore, the smart-doc+Torna solution is very powerful. Torna is currently in a high-speed iteration period. Welcome to experience Torna. We strive to provide the community with an efficient and easy-to-use interface documentation solution.
Upgrade suggestion
smart-doc can be smoothly upgraded based on the previous version, it is recommended to upgrade.
DEMO
Use the demo to easily play with the generation of interface documents, and display the effects of other user case documents: https://api.doubans.com/
well-known users
- iFlytek
- one plus
- Millet
- Hornet's nest
In August 2021, smart-doc also added some overseas users.