小胖求学系列之-文档生成利器(下)-smart-doc
叮叮叮。。。。一阵铃声响起，大家都陆续来到了课堂，看老师没来，小张和小胖又闲聊起来，小张问：怎么样，smart-doc好用吧。小胖笑着说：挺好用的，不过?
小张看卖关子，问到：不过什么，有什么新发现？小胖说：我在试用了这个之后，发现还能进一步简化，大家在用这个的时候，更多的是关心能不能快速帮我生成文档，没人想写那一套模版代码。小张说：你说的也有道理，那你有什么好办法。小胖说：可以借助maven自定义插件，把生成文档的模版代码全部隐藏起来，让大家只需要引入这个插件，需要生成文档的时候，点一下按钮就好了。小张说：这个想法不错，整个过程一共就两步，第一步引入插件，第二步点击按钮。小胖说：是的，给你看看我的代码。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.xxx.xx</groupId>
<artifactId>create-document</artifactId>
<version>3.0</version>
<packaging>maven-plugin</packaging>
<properties>
<maven-plugin-api.version>3.6.3</maven-plugin-api.version>
<maven-plugin-annotations.version>3.6.0</maven-plugin-annotations.version>
<maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
<java.version>1.8</java.version>
<versions-maven-plugin.version>2.7</versions-maven-plugin.version>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>${maven-plugin-api.version}</version>
</dependency>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
<artifactId>maven-plugin-annotations</artifactId>
<scope>provided</scope>
<version>${maven-plugin-annotations.version}</version>
</dependency>
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.7.9</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.10</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin.version}</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
</configuration>
</plugin>
<plugin>
<artifactId>maven-plugin-plugin</artifactId>
<version>3.6.0</version>
<executions>
<execution>
<id>default-addPluginArtifactMetadata</id>
<phase>package</phase>
<goals>
<goal>addPluginArtifactMetadata</goal>
</goals>
</execution>
<execution>
<id>default-descriptor</id>
<phase>process-classes</phase>
<goals>
<goal>descriptor</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>versions-maven-plugin</artifactId>
<version>${versions-maven-plugin.version}</version>
</plugin>
</plugins>
</build>
</project>
对应的java代码
package com.iflytek.ibk;
import com.power.common.util.DateTimeUtil;
import com.power.doc.builder.ApiDocBuilder;
import com.power.doc.model.ApiConfig;
import com.power.doc.model.ApiReqHeader;
import com.power.doc.model.RevisionLog;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import java.io.File;
import java.util.Objects;
/**
* 描述生成markdown格式文档
*
* @author xxx 2019/12/914:41
*/
@Mojo(name="markdown",defaultPhase= LifecyclePhase.PACKAGE)
public class CreateMarkDownPlugin extends AbstractMojo {
/**
* 文档输出目录(如果是html，则用默认路径)
*/
@Parameter(defaultValue = "${project.basedir}")
private File baseDir;
/**
* html文档访问格式
*/
@Parameter
private String port;
@Parameter
private RevisionParam revisionParam;
@Override
public void execute(){
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:"+port);
long start = System.currentTimeMillis();
try{
//生成markdown
createMarkdown(config);
}catch (Exception e){
getLog().error("生成文档失败，原因："+e.getMessage());
}
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
private void createMarkdown(ApiConfig config){
config.setCoverOld(true);
//设置为严格模式，Smart-doc将降至要求每个Controller暴露的接口写上标准文档注释
config.setStrict(true);
//当把AllInOne设置为true时，Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中
config.setAllInOne(true);
//Set the api document output path.
config.setOutPath(baseDir.getAbsolutePath());
//设置文档变更记录，没有需要可以不设置
if(Objects.nonNull(revisionParam)){
config.setRevisionLogs(
RevisionLog.getLog().setRevisionTime(DateTimeUtil.nowStrTime("yyyy-MM-dd"))
.setAuthor(revisionParam.getAuthor()).setRemarks(revisionParam.getRemark()).setStatus("update")
.setVersion(revisionParam.getVersion())
);
}
//，ApiDocBuilder提供markdown能力
ApiDocBuilder.builderControllersApi(config);
}
}
使用：
第一步：把这个插件安装到本地，然后业务项目的pom.xml这样引一下
<plugin>
<groupId>com.xxx.xx</groupId>
<artifactId>create-document</artifactId>
<version>3.0</version>
<configuration>
<!--这个端口号与项目端口号保持一致-->
<port>8080</port>
<!--文档变更记录 markdown的时候需要-->
<revisionParam>
<!--作者 -->
<author>xxx</author>
<!--版本号 -->
<version>V.0.3</version>
<!--升级内容 -->
<remark>完善接口文档</remark>
</revisionParam>
</configuration>
</plugin>
第二步：
然后点一下create-document:markdown就可以生成markdown文档了。
小胖说：如果你是使用者，实际上你只需要引入一次，点击插件按钮一次。
小张说：嗯。。。这个好，我要把这个推广到团队中去。
