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, completely achieving zero annotation intrusion. You only need to write according to java standard comments, 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
- Support interface debugging.
- 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.
- Supports 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-docOfficial website address: Document
1 Create the /src/main/resources/smart-doc.json configuration file in the project.
2 The configuration content is as follows (specify the output path of the document)
{
"outPath": "D://md2"
}
3 Add configuration under pom.xml
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.1.0</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库
加载不到导致报错,这时请使用excludes排除掉-->
<excludes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部
源代码而不是自动加载所有,因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效
率,因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<include>com.alibaba:fastjson</include>
<!-- 如果配置了includes的情况下, 使用了mybatis-plus的分页需要
include所使用的源码包 -->
<include>com.baomidou:mybatis-plus-extension</include>
<!-- 如果配置了includes的情况下, 使用了jpa的分页需要include所使用
的源码包 -->
<include>org.springframework.data:spring-data-commons</include>
</includes>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
<phase>compile</phase>
<goals>
<!--smart-doc提供了html、openapi、markdown等goal,可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
4 Run the plugin
5 Find the storage path and open the browser
6 test results