Smart-Doc Gradle Plugin

gradle closed pull requests

Introduce

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

Best Practice

smart-doc + Torna 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

smart-doc+torna

smart-doc+Torna文档自动化

Getting started

Add plugin

Using the plugins DSL:

plugins {
  id "com.ly.smart-doc" version "[最新版本]"
}

Using legacy plugin application:

buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url = uri("https://plugins.gradle.org/m2/") }
        mavenCentral()
    }
    dependencies {
        classpath 'com.ly.smart-doc:smart-doc-gradle-plugin:[最新版本]'
    }
}
apply(plugin = "com.ly.smart-doc")

Plugin options

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'
}

对于configFile的配置，你也可以通过gradle命令行来动态覆盖。在3.0.3之前，可以在build.gradle中添加动态获取configFile的配置, 例如：

smartdoc {
    configFile = project.hasProperty('smartdoc.configFile') ? file(project.getProperty('smartdoc.configFile')) : file("src/main/resources/smart-doc.json")
}

配置好后直接通过命令行覆盖：

gradle smartdoc -Psmartdoc.configFile=src/main/resources/smart-doc.json

在3.0.3之后，build.gradle中配置动态配置configFile很简单，插件完全具备覆盖的功能。

smartdoc {
    configFile =  file("src/main/resources/smart-doc.json")
}

配置后直接使用-Psmartdoc.configFile即可覆盖

对于多模块的Gradle，把smart-doc插件相关配置放到根目录build.gradle的subprojects中。

subprojects{
    apply plugin: 'com.ly.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

多模块和单模块项目是有区别，多模块不从根目录使用命令构建可能会导致模块间源代码加载失败，生成文档出现各种问题。

Create a json config

在自己的项目中创建一个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提供很多配置项，详细配置请参考官方文档

Generated document

Use Gradle command

//生成文档到html中
gradle smartDocRestHtml
//生成markdown
gradle smartDocRestMarkdown
//生成adoc
gradle smartDocRestAdoc
//生成postmanjson数据
gradle smartDocPostman
//生成Open Api 3.0 +规范的json文档,since smart-doc-gradle-plugin 1.1.4
gradle smartDocOpenApi
//生成rest接口文档并推送到Torna平台,@since 2.0.9
gradle tornaRest
//生成Jmeter性能压测脚本,since 3.0.0
gradle smartDocJmeter
//生成文档输出到Word,since 3.0.0
gradle word


// Apache Dubbo Rpc生成
// Generate html
gradle smartDocRpcHtml
// Generate markdown
gradle smartDocRpcMarkdown
// Generate adoc
gradle smartDocRpcAdoc
// 推送rpc接口到torna中
gradle tornaRpc