小胖求学系列之文档生成利器(下)smartdoc

       叮叮叮。。。。一阵铃声响起，大家都陆续来到了课堂，看老师没来，小张和小胖又闲聊起来，小张问：怎么样，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文档了。

小胖说：如果你是使用者，实际上你只需要引入一次，点击插件按钮一次。

小张说：嗯。。。这个好，我要把这个推广到团队中去。