smart-doc-gradle-plugin是smart-doc官方团队开发的gradle
插件,该插件从smart-doc 1.8.6版本开始提供,
使用smart-doc-gradle-plugin更方便用户集成到自己的项目中,集成也更加轻量,你不再需要在项目中编写单元测试来
启动smart-doc扫描代码分析生成接口文档。可以直接运行gradle
命令
或者是IDE中点击smart-doc-gradle-plugin预设好的task
即可生成接口文档。
smart-doc-gradle-plugin底层完全依赖于官方开源的smart-doc解析库,
因此整个使用过程中遇到问题或者是想查看完整解决方案请前往码云smart-doc的仓库查看wiki文档。
smart-doc + Torna 组成行业领先的文档生成和管理解决方案,使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档,自动将文档推送到Torna企业级接口文档管理平台。
Using the plugins DSL:
plugins {
id "com.github.shalousun.smart-doc" version "[最新版本]"
}
Using legacy plugin application:
buildscript {
repositories {
maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' }
maven { url = uri("https://plugins.gradle.org/m2/") }
mavenCentral()
}
dependencies {
classpath 'com.github.shalousun:smart-doc-gradle-plugin:[最新版本]'
}
}
apply(plugin = "com.github.shalousun.smart-doc")
Option | Default value | Description |
---|---|---|
configFile | src/main/resources/default.json | 插件配置文件 |
exclude | 无 | 排除一些无法自定下载的java lib sources,例如:exclude 'org.springframework.boot:spring-boot-starter-tomcat' |
include | 无 | 让插件自定下载指定的java lib sources,例如:include 'org.springframework.boot:spring-boot-starter-tomcat' |
Example setting of options:
smartdoc {
configFile = file("src/main/resources/smart-doc.json")
// exclude example
// exclude artifact
exclude 'org.springframework.boot:spring-boot-starter-tomcat'
// exclude artifact use pattern
exclude 'org.springframework.boot.*'
// 你可以使用include配置来让插件自动加载指定依赖的source.
include 'org.springframework.boot:spring-boot-starter-tomcat'
}
对于多模块的gradle,把smart-doc插件相关配置放到根目录build.gradle的subprojects中。
subprojects{
apply plugin: 'com.github.shalousun.smart-doc'
smartdoc {
//
configFile = file("src/main/resources/smart-doc.json")
// exclude artifact
exclude 'org.springframework.boot:xx'
exclude 'org.springframework.boot:ddd'
// 你可以使用include配置来让插件自动加载指定依赖的source.
include 'org.springframework.boot:spring-boot-starter-tomcat'
}
}
多模块smart-doc的实战demo参考
https://gitee.com/devin-alan/smart-doc-gradle-plugin-demo
多模块和单模块项目是有区别,多模块不从根目录使用命令构建可能会导致模块间源代码加载失败,生成文档出现各种问题。
在自己的项目中创建一个json配置文件,如果是多个模块则放到需要生成文档的模块中,smart-doc-gradle-plugin插件会根据这个配置生成项目的接口文档。
例如在项目中创建/src/main/resources/smart-doc.json
。配置内容参考如下。
最小配置单元:
{
"outPath": "D://md2" //指定文档的输出路径 相对路径时请写 ./ 不要写 / eg:./src/main/resources/static/doc
}
如果你想把html文档也打包到应用中随着服务一起访问,则建议你配置路径为:src/main/resources/static/doc。 服务访问配置参考
仅仅需要上面一行配置就能启动smart-doc-gradle-plugin插件。
smart-doc提供很多配置项, 详细配置请参考官方文档
//生成html
gradle smartDocRestHtml
//生成markdown
gradle smartDocRestMarkdown
//生成adoc
gradle smartDocRestAdoc
//生成postmanjson数据
gradle smartDocPostman
//生成Open Api 3.0 +规范的json文档
gradle smartDocOpenApi
//生成rest接口文档并推送到Torna平台
gradle tornaRest
// Apache Dubbo Rpc生成
// Generate html
gradle smartDocRpcHtml
// Generate markdown
gradle smartDocRpcMarkdown
// Generate adoc
gradle smartDocRpcAdoc
当你使用Idea时,可以通过maven Helper插件选择生成何种文档。
如果你需要自己构建,那可以使用下面命令,构建需要依赖Java 1.8。
// 将gradle插件暗转到本地
gradle publishToMavenLocal
// 将gradle插件发布到自己nexus仓库,自己修改build.gradle中的仓库地址配置
gradle publish
smart-doc-gradle-plugin is under the Apache 2.0 license. See the LICENSE file for details.
注意: smart-doc源代码文件全部带有版权注释,使用关键代码二次开源请保留原始版权,否则后果自负!
排名不分先后,更多接入公司,欢迎在https://gitee.com/smart-doc-team/smart-doc/issues/I1594T登记(仅供开源用户参考)
愿意参与构建smart-doc或者是需要交流问题可以加入qq群:
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。