update README.md

This commit is contained in:
oppofind 2020-03-13 10:59:57 +08:00
parent 33203a6d72
commit 1f69b0c1ca
2 changed files with 186 additions and 191 deletions

View File

@ -1,186 +1,181 @@
<h1 align="center"><a href="https://github.com/shalousun/smart-doc" target="_blank">Smart-Doc Project</a></h1>
## Introduce
smart-doc是一个java restful api文档生成工具smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。
smart-doc完全基于接口源码分析来生成接口文档完全做到零注解侵入你只需要按照java标准注释的写smart-doc就能帮你生成一个简易明了的markdown
或是一个像GitBook样式的静态html文档。如果你已经厌倦了swagger等文档工具的无数注解和强侵入污染那请拥抱smart-doc吧
## Features
- 零注解、零学习成本、只需要写标准java注释。
- 基于源代码接口定义自动推导,强大的返回结构推导。
- 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
- 支持Callable,Future,CompletableFuture等异步接口返回的推导。
- 支持JavaBean上的JSR303参数校验规范。
- 对json请求参数的接口能够自动生成模拟json参数。
- 对一些常用字段定义能够生成有效的模拟值。
- 支持生成json返回值示例。
- 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
- 支持生成多种格式文档Markdown、HTML5、Asciidoctor、Postman json。
- 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
- 开放文档数据,可自由实现接入文档管理系统。
- 支持导出错误码和定义在代码中的各种字典码到接口文档。
## Getting started
smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/sunyurepository/api-doc-test.git)。
```
# git clone https://gitee.com/sunyurepository/api-doc-test.git
```
你可以启动这个Spring Boot的项目然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。
### Dependency
#### maven
```
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.8.1</version>
<scope>test</scope>
</dependency>
```
#### gradle
```
testCompile 'com.github.shalousun:smart-doc:1.8.1'
```
### Create a unit test
通过运行一个单元测试来让Smart-doc为你生成一个简洁明了的api文档最简单例子如下
```
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
//true会严格要求代码中必须有java注释首次体验可关闭正式产品推荐设置true
config.setStrict(true);
//当把AllInOne设置为true时Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中
config.setAllInOne(true);
//Set the api document output path.
config.setOutPath("d:\\md");
//生成Markdown文件
ApiDocBuilder.builderControllersApi(config);
}
```
**详细用例:**
```
public class ApiDocTest {
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080"); //非必须像
//true会严格要求注释推荐设置true
config.setStrict(true);
//true会将文档合并导出到一个markdown
config.setAllInOne(false);
//生成html时加密文档名不暴露controller的名称
config.setMd5EncryptedHtmlName(true);
//指定文档输出路径
//@since 1.7 版本开始选择生成静态html doc文档可使用该路径DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
// @since 1.2,如果不配置该选项则默认匹配全部的controller,
// 如果需要配置有多个controller可以使用逗号隔开
config.setPackageFilters("com.power.doc.controller");
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourceCodePaths(
//自1.7.0版本开始,在此处可以不设置本地代码路径,单独添加外部代码路径即可
// SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
SourceCodePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
);
//since 1.7.5
//如果该选项的值为false,则smart-doc生成allInOne.md文件的名称会自动添加版本号
config.setCoverOld(true);
//since 1.7.5
//设置项目名(非必须),如果不设置会导致在使用一些自动添加标题序号的工具显示的序号不正常
config.setProjectName("抢购系统");
//since 1.7.9 新增是否显示接口作者 默认true
config.setShowAuthor(false);
//设置请求头,如果没有请求头,可以不用设置
config.setRequestHeaders(
ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
);
//对于外部jar的类编译后注释会被擦除无法获取注释但是如果量比较多请使用setSourcePaths来加载外部代码
//如果有这种场景则自己添加字段和注释api-doc后期遇到同名字段则直接给相应字段加注释
config.setCustomResponseFields(
CustomRespField.field().setName("success").setDesc("成功返回true,失败返回false"),
CustomRespField.field().setName("message").setDesc("接口响应信息"),
CustomRespField.field().setName("data").setDesc("接口响应数据"),
CustomRespField.field().setName("code").setValue("00000").setDesc("响应代码")
);
//设置项目错误码列表,设置自动生成错误列表,
List<ApiErrorCode> errorCodeList = new ArrayList<>();
for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
ApiErrorCode errorCode = new ApiErrorCode();
errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
errorCodeList.add(errorCode);
}
//如果没需要可以不设置
config.setErrorCodes(errorCodeList);
//非必须只有当setAllInOne设置为true时文档变更记录才生效https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
config.setRevisionLogs(
RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
);
//since 1.7.5
//文档添加数据字典
config.setDataDictionaries(
ApiDataDictionary.dict().setTitle("订单状态").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
ApiDataDictionary.dict().setTitle("订单状态1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
);
long start = System.currentTimeMillis();
ApiDocBuilder.builderControllersApi(config);
//@since 1.7+版本开始smart-doc支持生成带书签的html文档html文档可选择下面额方式
//HtmlApiDocBuilder.builderControllersApi(config);
//@since 1.8.1+版本开始,方法名做了调整
//HtmlApiDocBuilder.buildApiDoc(config);
//@since 1.7+版本开始smart-doc支撑生成AsciiDoc文档你可以把AsciiDoc转成HTML5的格式。
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);
//@since 1.8.1+版本开始,方法名做了调整
//AdocDocBuilder.buildApiDoc(config);
//@since 1.7.8,smart-doc支持导出Postman测试的json
//PostmanJsonBuilder.buildPostmanApi(config);
//@since 1.8.1+版本开始,方法名做了调整
//PostmanJsonBuilder.buildPostmanCollection(config)
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
}
```
#### smart-doc-maven-plugin
从smart-doc 1.7.9开始官方提供了maven插件使用smart-doc的maven插件后不再需要创建单元测试。
[插件使用说明](https://gitee.com/sunyurepository/smart-doc/wikis/smart-doc%20maven插件?sort_id=1791450)
### Generated document example
[点击查看文档生成文档效果图](https://gitee.com/sunyurepository/smart-doc/wikis/文档效果图?sort_id=1652819)
## Building
如果你需要自己构建那可以使用下面命令构建需要依赖Java 1.8。
```
mvn clean install -Dmaven.test.skip=true
```
## Releases
[发布记录](https://gitee.com/sunyurepository/smart-doc/blob/master/CHANGELOG.md)
## Other reference
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
- [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800)
## License
Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://gitee.com/sunyurepository/smart-doc/blob/master/license.txt) file for details.
**注意:** smart-doc源代码文件全部带有版权注释使用关键代码二次开源请保留原始版权否则后果自负
## Who is using
> 排名不分先后,更多接入公司,欢迎在[https://gitee.com/sunyurepository/smart-doc/issues/I1594T](https://gitee.com/sunyurepository/smart-doc/issues/I1594T)登记(仅供开源用户参考)
![iFLYTEK](https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/iflytek.png)
&nbsp;&nbsp;<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/oneplus.png" title="一加" width="83px" height="83px"/>
&nbsp;&nbsp;<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/xiaomi.png" title="小米" width="170px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/yuanmengjiankang.png" title="远盟健康" width="260px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/zhongkezhilian.png" title="中科智链" width="272px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/puqie_gaitubao_100x100.jpg" title="普切信息科技" width="83px" height="83px"/>
## Contact
愿意参与构建smart-doc或者是需要交流问题可以加入qq群
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/smart-doc-qq.png" title="qq群" width="200px" height="200px"/>
<h1 align="center"><a href="https://github.com/shalousun/smart-doc" target="_blank">Smart-Doc Project</a></h1>
## Introduce
smart-doc是一个java restful api文档生成工具smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。
smart-doc完全基于接口源码分析来生成接口文档完全做到零注解侵入你只需要按照java标准注释的写smart-doc就能帮你生成一个简易明了的markdown
或是一个像GitBook样式的静态html文档。如果你已经厌倦了swagger等文档工具的无数注解和强侵入污染那请拥抱smart-doc吧
## Features
- 零注解、零学习成本、只需要写标准java注释。
- 基于源代码接口定义自动推导,强大的返回结构推导。
- 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
- 支持Callable,Future,CompletableFuture等异步接口返回的推导。
- 支持JavaBean上的JSR303参数校验规范。
- 对json请求参数的接口能够自动生成模拟json参数。
- 对一些常用字段定义能够生成有效的模拟值。
- 支持生成json返回值示例。
- 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
- 支持生成多种格式文档Markdown、HTML5、Asciidoctor、Postman json。
- 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
- 开放文档数据,可自由实现接入文档管理系统。
- 支持导出错误码和定义在代码中的各种字典码到接口文档。
## Getting started
smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/sunyurepository/api-doc-test.git)。
```
# git clone https://gitee.com/sunyurepository/api-doc-test.git
```
你可以启动这个Spring Boot的项目然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。
### Add Maven plugin
Smart-doc官方目前由于人力有限仅实现了maven 插件使用Gradle的请走单元测试方式集成Smart-doc。
#### add plugin
```
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>[最新版本]</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码如果一些框架依赖库加载不到导致报错这时请使用excludes排除掉-->
<excludes>
<!--格式为groupId:artifactId;参考如下-->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc则将phase注释掉-->
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
```
#### Add Config
在项目中添加创建一个`smart-doc.json`配置文件,插件读取这个配置来生成项目的文档,这个配置内容实际上就是以前采用单元测试编写的`ApiConfig`转成json后的结果因此关于配置项说明可以参考原来单元测试的配置。
**最小配置单元:**
```
{
"outPath": "D://md2" //指定文档的输出路径
}
```
**详细配置说明**
```
{
"serverUrl": "http://127.0.0.1", //设置服务器地址,非必须
"isStrict": false, //是否开启严格模式
"allInOne": true, //是否将文档合并到一个文件中一般推荐为true
"outPath": "D://md2", //指定文档的输出路径
"coverOld": true, //是否覆盖旧的文件主要用于mardown文件覆盖
"packageFilters": "",//controller包过滤多个包用英文逗号隔开
"md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
"projectName": "smart-doc",//配置自己的项目名称
"skipTransientField": true,//目前未实现
"showAuthor":true,//是否显示接口作者名称默认是true,不想显示可关闭
"dataDictionaries": [ //配置数据字典,没有需求可以不设置
{
"title": "http状态码字典", //数据字典的名称
"enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称
"codeField": "code",//数据字典字典码对应的字段名称
"descField": "message"//数据字典对象的描述信息字典
}
],
"errorCodeDictionaries": [{ //错误码列表,没有需求可以不设置
"title": "title",
"enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类
"codeField": "code",//错误码的code码字段名称
"descField": "message"//错误码的描述信息对应的字段名
}],
"revisionLogs": [ //设置文档变更记录,没有需求可以不设置
{
"version": "1.0", //文档版本号
"status": "update", //变更操作状态,一般为:创建、更新等
"author": "author", //文档变更作者
"remarks": "desc" //变更描述
}
],
"customResponseFields": [ //自定义添加字段和注释api-doc后期遇到同名字段则直接给相应字段加注释非必须
{
"name": "code",//覆盖响应码字段
"desc": "响应代码",//覆盖响应码的字段注释
"value": "00000"//设置响应码的值
}
],
"requestHeaders": [ //设置请求头,没有需求可以不设置
{
"name": "token",
"type": "string",
"desc": "desc",
"required": false,
"since": "-"
}
],
"sourceCodePaths": [ //设置代码路径smart-doc默认会自动加载src/main/java, 没有需求可以不设置
{
"path": "src/main/java",
"desc": "测试"
}
]
}
```
上面的json配置实例中只有"outPath"是必填项。
**注意:** 对于老用户完全可以通过`Fastjson`或者是`Gson`库将`ApiConfig`转化成json配置。
#### Use Maven Command
添加好插件和配置文件后可以直接运行maven命令生成文档。
```
//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
```
**注意:** 尤其在window系统下如果实际使用maven命令行执行文档生成可能会出现乱码因此需要在执行时指定`-Dfile.encoding=UTF-8`。
#### Use Idea
![idea中smart-doc-maven插件使用](https://images.gitee.com/uploads/images/2019/1215/004902_b0c153d6_144669.png "idea.png")
### Use Junit Test
从smart-doc 1.7.9开始官方提供了maven插件使用smart-doc的maven插件后不再需要创建单元测试。
[单元测试生成文档](https://gitee.com/sunyurepository/smart-doc/wikis/单元测试集成smart-doc?sort_id=1990284)
### Generated document example
[点击查看文档生成文档效果图](https://gitee.com/sunyurepository/smart-doc/wikis/文档效果图?sort_id=1652819)
## Building
如果你需要自己构建smart-doc那可以使用下面命令构建需要依赖Java 1.8。
```
mvn clean install -Dmaven.test.skip=true
```
## Releases
[发布记录](https://gitee.com/sunyurepository/smart-doc/blob/master/CHANGELOG.md)
## Other reference
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
- [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800)
## License
Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://gitee.com/sunyurepository/smart-doc/blob/master/license.txt) file for details.
**注意:** smart-doc源代码文件全部带有版权注释使用关键代码二次开源请保留原始版权否则后果自负
## Who is using
> 排名不分先后,更多接入公司,欢迎在[https://gitee.com/sunyurepository/smart-doc/issues/I1594T](https://gitee.com/sunyurepository/smart-doc/issues/I1594T)登记(仅供开源用户参考)
![iFLYTEK](https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/iflytek.png)
&nbsp;&nbsp;<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/oneplus.png" title="一加" width="83px" height="83px"/>
&nbsp;&nbsp;<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/xiaomi.png" title="小米" width="170px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/yuanmengjiankang.png" title="远盟健康" width="260px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/zhongkezhilian.png" title="中科智链" width="272px" height="83px"/>
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/puqie_gaitubao_100x100.jpg" title="普切信息科技" width="83px" height="83px"/>
## Contact
愿意参与构建smart-doc或者是需要交流问题可以加入qq群
<img src="https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/smart-doc-qq.png" title="qq群" width="200px" height="200px"/>

View File

@ -87,8 +87,8 @@ public class DocUtil {
fieldValue.put("message-string", "success,fail".split(",")[RandomUtil.randomInt(0, 1)]);
fieldValue.put("date-string", DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("date-date", DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("begintime-date",DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("endtime-date",DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("begintime-date", DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("endtime-date", DateTimeUtil.dateToStr(new Date(), DateTimeUtil.DATE_FORMAT_DAY));
fieldValue.put("state-int", String.valueOf(RandomUtil.randomInt(0, 10)));
fieldValue.put("state-integer", String.valueOf(RandomUtil.randomInt(0, 10)));
fieldValue.put("flag-int", String.valueOf(RandomUtil.randomInt(0, 10)));
@ -419,9 +419,9 @@ public class DocUtil {
if ("file".equals(formData.getType())) {
continue;
}
if(formData.getKey().contains("[]")){
String key = formData.getKey().substring(0,formData.getKey().indexOf("["));
formDataMap.put(key,formData.getValue()+"&"+key+"="+formData.getValue());
if (formData.getKey().contains("[]")) {
String key = formData.getKey().substring(0, formData.getKey().indexOf("["));
formDataMap.put(key, formData.getValue() + "&" + key + "=" + formData.getValue());
continue;
}
formDataMap.put(formData.getKey(), formData.getValue());