小胖求学系列之-文档生成利器(下)-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文档了。
小胖说:如果你是使用者,实际上你只需要引入一次,点击插件按钮一次。
小张说:嗯。。。这个好,我要把这个推广到团队中去。
小胖求学系列之-文档生成利器(下)-smart-doc的更多相关文章
- 小胖求学系列之-文档生成利器(上)-smart-doc
最近小胖上课总是挂着黑眼圈,同桌小张问:你昨晚通宵啦?小胖有气无力的说到:最近开发的项目接口文档没写,昨晚补文档补了很久,哎,昨晚只睡了2个小时.小张说:不是有生成文档工具吗,类似swagger2.s ...
- 入坑 docsify,一款神奇的文档生成利器!
layout: postcategory: javatitle: 入坑 docsify,一款神奇的文档生成利器!tagline: by 沉默王二tags: - java Guide 哥是我认识的一个非 ...
- 【C#附源码】数据库文档生成工具支持(Excel+Html)
[2015] 很多时候,我们在生成数据库文档时,使用某些工具,可效果总不理想,不是内容不详细,就是表现效果一般般.很多还是word.html的.看着真是别扭.本人习惯用Excel,所以闲暇时,就简单的 ...
- 微软开源全新的文档生成工具DocFX
微软放弃Sandcastle有些年头了,微软最近开源了全新的文档生成工具DocFX,目前支持C#和VB,类似JSDoc或Sphinx,可以从源代码中提取注释生成文档之外,而且还有语法支持你加入其他的文 ...
- DBImport v3.44 中文版发布:数据库数据互导及文档生成工具(IT人员必备)
前言: 距离上一个版本V3.3版本的文章发布,已经是1年10个月前的事了. 其实版本一直在更新,但也没什么大的功能更新,总体比较稳定,所以也不怎么写文介绍了. 至于工作上的事,之前有半年时间跑去学英语 ...
- .NET平台开源项目速览(4).NET文档生成工具ADB及使用
很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习一些开源项目的过程中,官方没有提供CHM帮助文档,所以为了快速的了解项目结构和注释.就生成文档来自己看,非常好用.这也是一个学习方法吧 ...
- (转)Doxygen文档生成工具
http://blog.csdn.net/lostaway/article/details/6446786 Doxygen 是一个支持 C/C++,以及其它多种语言的跨平台文档生成工具.如同 Java ...
- Sandcastle----强大的C#文档生成工具
最近客户索要产品的二次开发类库文档,由于开发过程中并没有考虑过此类文档,而且项目规范比较,持续时间比较长,经手人比较多,还真是麻烦,如果人工制作文档需要是一个比较大的工程.还好有这个文档生成工具,能够 ...
- JAVA基础学习之命令行方式、配置环境变量、进制的基本转换、排序法、JAVA文档生成等(1)
1.命令行方式 dos命令行,常见的命令: dir:列出当前目录下的文件以及文件夹 md:创建目录 rd:删除目录 cd:进入指定目录 cd..:退回到上一级目录 cd/:退回到根目录 del:删除文 ...
随机推荐
- ES6学习 let const
1.前言 发现网易云笔记 单纯的记笔记没什么意思,所以今天来博客园写学习感受了,毕设做了休息时间就来写写新学的知识 哈哈哈 !! 2.ES6 就是JavaScript 语言的下一代标准,2015年6月 ...
- django_5:表单1——文件上传
上传文件1 class UserForm(forms.Form): name = forms.CharField() headImg = forms.FileField() def regist(re ...
- VLAN配置及Trunk接口配置
实验拓扑 1.检验连通性,PC2 ping PC3,PC2 ping PC4 ,都能ping 通 2.创建vlan 3.配置access接口 在S1上配置E0/0/2为vlan10和E0/0/3为vl ...
- [需求设计]从一个小需求感受Redis的独特魅力
分享一个简单的小需求应该怎么设计实现以及有关Redis的使用 Redis在实际应用中使用的非常广泛,本篇文章就从一个简单的需求说起,为你讲述一个需求是如何从头到尾开始做的,又是如何一步步完善的.之前写 ...
- Java8 Stream终端操作使用详解
话不多说,自己挖的坑自己要填完,今天就给大家讲完Java8中Stream的终端操作使用详解.Stream流的终端操作主要有以下几种,我们来一一讲解. forEach() forEachOrdered( ...
- php 精度计算问题
PHP var_dump(intval(0.58 * 100)); 正确结果是 57,而不是 58 浮点运算惹的祸 其实这些结果都并非语言的 bug,但和语言的实现原理有关, js 所有数字统一为 N ...
- MATLAB数值计算——0
目录 MATLAB数值计算 1.solve() 2.fzero() 3.fsolve() MATLAB数值计算 MATLAB中文论坛基础板块常见问题归纳(出处: MATLAB中文论坛) 登录http: ...
- 【java】使用java.util的【Collections】简化List创建
我们在创建一个List并往其中加入一个元素的时候一般会这么做: public List<User> getCurrentUser() { List<User> users = ...
- 顺序表-C语言实现
顺序存储线性表的结构体: #define MAXSIZE 100 //数组最大长度 typedef int ElemType; //元素类型 typedef struct //定义线性表结构体 { E ...
- 《Windows内核安全与驱动开发》 3.2 内存与链表
<Windows内核安全与驱动开发>阅读笔记 -- 索引目录 <Windows内核安全与驱动开发> 3.2 内存与链表 1. 尝试生成一个链表头并将其初始化. 2. 尝试向内存 ...