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 of swagger that uses a large number of annotations to generate documents. smart-doc generates interface documentation based entirely on interface source code analysis, completely achieving zero annotation intrusion, you only need to write in accordance with java standard annotations, smart-doc can help you generate a simple and clear markdown or a static GitBook style html document. If you are tired of the countless annotations and intrusive pollution of documentation tools such as swagger, then please embrace smart-doc!
Features
- Zero annotation, zero learning cost, only need to write standard java annotations.
- Automatic derivation based on source code interface definition, powerful return structure derivation.
- Support Spring MVC, Spring Boot, Spring Boot Web Flux (controller writing method).
- Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture.
- Support JSR303 parameter verification specification on JavaBean, support group verification.
- The interface for json request parameters can automatically generate simulated json parameters.
- The definition of some common fields can generate valid analog values.
- Support generating json return value examples.
- Supports loading source code from outside the project to generate field comments (including jar packages released by standard specifications).
- Support to generate documents in multiple formats: Markdown, HTML5, Asciidoctor, Postman collection, Open Api 3.0+.
- It is easy to view static HTML5 api documents online on the Spring Boot service.
- Open document data, freely realize access to document management system.
- A code comment detection tool, friends who don't write comments can't escape the eye.
- Plug-in quick integration (support maven and gradle plugins).
- Support Apache Dubbo rpc document generation.
Smart-doc and other tools support
| Features | smart-doc | swagger | Non-swagger ecosystem tools |
| Code intrusion | no | Annotation is severely invasive | Some tools are the same as swagger, and some tools also use source code analysis |
| Integration complexity | Simple, just plug-in | Too complicated | |
| Plugin support | There are gradle and maven plugins | No plugins | Basically no plugins |
| openapi specification support | Support openapi 3.0 | Fully support the version of openapi | |
| CI build integration | Can be used in the ci construction phase maven or gradle command Start the plugin to generate documentation
|
not support | Hardly support |
| Centralized document center integration | Will exclusively support integration in the future The mysterious centralized document management center, Create an automatic and integrated enterprise-level interface document solution |
not support | Hardly support |
| Maintain continuity | Trustworthy, with a large user base after open source, and continuous maintenance | Many users worldwide, open source maintenance is trustworthy | Low maintenance, high risk of stoppage |
| mock request | Not supported (this is not a requirement of a mature R&D team) | stand by | unknown |
update content
1. Modify the bug in 1.9.8 to enable strict check comment mode. 2. Modify the parsing error when using generic array parameters. 3. Fix the array parsing error in ResponseEntity. 4. Fix the document serial number error after the controller method is marked ignore. 5. Add support for parsing the path attribute of @RequestMapping annotation. 6. Fix the problem that the formdata form in postman does not display description information. 7. html5 allInOne template supports code highlighting.
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 relevant maven or gradle plugins. It is also recommended to use smart-doc by using plug-ins.
https://gitee.com/smart-doc-team/smart-doc-maven-plugin
Upgrade suggestion
Fixed some bugs reported by users. This upgrade does not involve api changes.
DEMO
Use demo to easily play interface document generation, and display the effect of other user case documents: https://api.doubans.com/
Well-known users
- IFlytek
- OnePlus
- Xiaomi