在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
Smart-Doc Maven PluginIntroducesmart-doc-maven-plugin是smart-doc官方团队开发的 Best Practicesmart-doc + Torna 组成行业领先的文档生成和管理解决方案,使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档,自动将文档推送到Torna企业级接口文档管理平台。 Getting startedAdd plugin<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>【最新版】</version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>测试</projectName> <!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库加载不到导致报错,这时请使用excludes排除掉--> <excludes> <!--格式为:groupId:artifactId;参考如下--> <!--1.0.7版本开始你还可以用正则匹配排除,如:poi.* --> <exclude>com.alibaba:fastjson</exclude> </excludes> <!--自1.0.8版本开始,插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载,因此使用时需要注意--> <!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效率,因此你可以使用includes来让插件加载你配置的组件--> <includes> <!--格式为:groupId:artifactId;参考如下--> <include>com.alibaba:fastjson</include> </includes> </configuration> <executions> <execution> <!--如果不需要在执行编译时启动smart-doc,则将phase注释掉--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions></plugin> Create a json config在自己的项目中创建一个json配置文件,smart-doc-maven-plugin插件会根据这个配置生成项目的接口文档。例如在项目中创建 最小配置单元: { "outPath": "D://md2" //指定文档的输出路径 相对路径时请写 ./ 不要写 / eg:./src/main/resources/static/doc}
仅仅需要上面一行配置就能启动smart-doc-maven-plugin插件,根据自己项目情况更多详细的配置参考下面。 smart-doc提供很多配置项,详细配置请参考官方文档 Generated documentRun plugin with maven command//生成htmlmvn -Dfile.encoding=UTF-8 smart-doc:html//生成markdownmvn -Dfile.encoding=UTF-8 smart-doc:markdown//生成adocmvn -Dfile.encoding=UTF-8 smart-doc:adoc//生成postmanjson数据mvn -Dfile.encoding=UTF-8 smart-doc:postman// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5mvn -Dfile.encoding=UTF-8 smart-doc:openapi// 生成文档推送到Torna平台mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest// Apache Dubbo Rpc文档// Generate htmlmvn -Dfile.encoding=UTF-8 smart-doc:rpc-html// Generate markdownmvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown// Generate adocmvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc 注意: 尤其在window系统下,如果实际使用maven命令行执行文档生成,可能会出现乱码,因此需要在执行时指定 查看maven的编码 # mvn -versionApache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00)Maven home: D:\ProgramFiles\maven\bin\..Java version: 1.8.0_191, vendor: Oracle CorporationJava home: D:\ProgramFiles\Java\jdk1.8.0_191\jreDefault locale: zh_CN, platform encoding: GBKOS name: "windows 10", version: "10.0", arch: "amd64", family: "dos" Run plugin in IDEA当你使用Idea时,可以通过maven Helper插件选择生成何种文档。 Generated document exampleBuilding如果你需要自己构建,那可以使用下面命令,构建需要依赖Java 1.8。 mvn clean install -Dmaven.test.skip=true ReleasesLicensesmart-doc-maven-plugin is under the Apache 2.0 license. See the LICENSE file for details. 注意: smart-doc源代码文件全部带有版权注释,使用关键代码二次开源请保留原始版权,否则后果自负! Who is using
Contact愿意参与构建smart-doc或者是需要交流问题可以加入qq群: |
请发表评论