smart-doc is a tool that supports java restful api and Apache Dubbo rpc interface document generation at the same time. smart-doc subverts the traditional implementation method like swagger that uses annotation intrusion to generate documents.
smart-doc generates interface documents based entirely on interface source code analysis, and completely achieves zero annotation intrusion. You only need to write according to java standard annotations, and smart-doc can help you generate a simple and clear markdown or a static file like GitBook style html document. If you are tired of the countless annotations and strong intrusion pollution of documentation tools such as swagger, please embrace smart-doc!
Features
- Supports generating API documentation in html5 format for debuggable interfaces.
- Zero annotations, zero learning costs, only need to write standard java annotations.
- Automatic derivation based on source code interface definition, powerful return structure derivation.
- Supports Spring MVC, Spring Boot, Spring Boot Web Flux (controller writing), JAX-RS specifications.
- Support the derivation returned by Callable, Future, CompletableFuture and other asynchronous interfaces.
- Support the JSR303 parameter verification specification on JavaBean, and 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 jar packages released by standard specifications).
- Supports generating documents in multiple formats: Markdown, HTML5, Asciidoctor, Postman collection, Open Api 3.0+.
- Easily view static HTML5 api documents online on the Spring Boot service.
- Open document data, free access to document management system.
- A code comment detection tool, friends who don't write comments can't escape the eyes of the eye.
- Plug-in fast integration (support maven and gradle plug-ins).
- Support Apache Dubbo rpc document generation.
- Support domestic Solon application development framework.
Smart-doc and other tool support
| Features | smart-doc | swagger |
| code hacking | none | Annotation is very intrusive |
| Integration complexity | Simple, just plug-in | Complicated |
| plugin support | There are gradle and maven plugins | no plugin |
| openapi specification support | support openapi 3.0 | A version that fully supports openapi |
| CI build integration | Available in ci build phase maven or gradle command Start the plugin to generate documentation
|
not support |
| Centralized Document Center Integration | Already docked with torna enterprise-level interface document management platform |
not support |
| maintenance continuity | It is trustworthy, has a large user base after open source, and has been continuously maintained | Many users around the world, open source maintenance is trustworthy |
| interface debug | Since version 2.0.0, debugging has been supported, and the page is much more beautiful than swagger. | support |
Smart-doc has almost realized the function of swagger ui since 2.0.0, and it is more concise and generous than swagger ui, and it is more in line with the demands of domestic developers. The current function of smart-doc has also been
It exceeds what swagger provides for java developers. Of course, smart-doc itself only supports scanning codes to generate openapi 3.0 documents, and the generated openapi 3.0 documents can also be imported into other ui for rendering and display.
In the past two years, many domestic developers have developed non-intrusive idea document generation plug-ins, and we are also continuing to pay attention to the development of these plug-ins. At present, the integration of these idea plug-ins is definitely simpler than smart-doc, and the document generation speed is faster than smart-doc (idea plug-ins do not compile these stages), but currently these plug-ins have not solved the problem of multi-module projects and dependent modules. The comment problem in the scene, the use case support collected during the development of smart-doc is not perfect. Taken together, smart-doc is still the best tool for domestic java web developers to generate documentation.
Update details
2. After using cron expression in mock value Escape value problem. [#487] ( https://github.com/smart-doc-group/smart-doc/issues/487 )
3. Support gson alias resolution. [#485] ( https://github.com/smart-doc-group/smart-doc/pull/485 )
4. Fix the parent class interface bug that cannot be obtained from multi-layer inheritance . [#480] ( https://github.com/smart-doc-group/smart-doc/issues/480 )
5. Support the use of multiple @RequestBody in the interface . [#pr475] ( https://github.com/smart-doc-group/smart-doc/pull/475 )
6. Upgrade jquery , [#pr474] ( https://github.com/smart-doc-group /smart-doc/pull/474 )
7. Fix file field required setting, [#pr470] ( https://github.com/smart-doc-group/smart-doc/pull/470 )
8. Fix multi- path error , [#466] ( https://github.com/smart-doc-group/smart-doc/issues/466)
debug page effect
maven or gradle plugin
Smart-doc official In order to facilitate users to quickly and non-intrusively integrate smart-doc's document api generation capabilities, we develop related maven or gradle plug-ins. It is also recommended to use smart-doc as a plug-in.
https://gitee.com/smart-doc-team/smart-doc-maven-plugin
Official Recommended Program
smart-doc + Torna form an industry-leading document generation and management solution, use smart-doc to complete Java source code analysis and extract comments to generate API documents without intrusion, and automatically push documents to Torna enterprise-level interface document management platform.
smart-doc+Torna document automation
smart-doc has been used to replace swagger in many domestic companies, and even the top 3 domestic manufacturers have secondary development versions of smart-doc. Torna's future goal is to catch up with and surpass Yapi. Smart-doc's analysis ability for java spring technology stack is currently the strongest in the industry (if you are not convinced, use the tool to run smart-doc's analysis demo). So the smart-doc+Torna solution is 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 upgraded smoothly for users this time. The 2.6 version series has undergone major rectification. The previous version is not stable enough. It is recommended to upgrade to the latest 2.6.8.
This update is also very grateful for the contributions of community students.
DEMO
Use the demo to easily play with the generation of interface documents, and the effect of other user case documents: https://api.doubans.com/
famous user
- HKUST Xunfei
- one plus
- Millet
- Hornet's nest
- SF Express
In August 2021, smart-doc also added some overseas users.