# smart-doc-maven-plugin
**Repository Path**: jx372884807/smart-doc-maven-plugin
## Basic Information
- **Project Name**: smart-doc-maven-plugin
- **Description**: smart-doc官方maven插件
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 75
- **Created**: 2021-11-02
- **Last Updated**: 2021-11-02
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
## Introduce
smart-doc-maven-plugin是smart-doc官方团队开发的`maven`插件，该插件从smart-doc 1.7.9版本开始提供，
使用smart-doc-maven-plugin更方便用户集成到自己的项目中，集成也更加轻量，你不再需要在项目中编写单元测试来
启动smart-doc扫描代码分析生成接口文档。可以直接运行`maven`命令
或者是IDE中点击smart-doc-maven-plugin预设好的`goal`即可生成接口文档。
[关于smart-doc](https://gitee.com/sunyurepository/smart-doc)
## Getting started
### Add plugin
```
com.github.shalousun
smart-doc-maven-plugin
【最新版】
./src/main/resources/smart-doc.json
测试
com.alibaba:fastjson
compile
html
```
### Create a json config
在自己的项目中创建一个json配置文件，smart-doc-maven-plugin插件会根据这个配置生成项目的接口文档。
例如在项目中创建`/src/main/resources/smart-doc.json`。配置内容参考如下。
**最小配置单元:**
```
{
"outPath": "D://md2" //指定文档的输出路径 相对路径时请写 ./ 不要写 / eg:./src/main/resources/static/doc
}
```
**详细配置说明:**
```
{
"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,//目前未实现
"dataDictionaries": [ //配置数据字典，没有需求可以不设置
{
"title": "订单状态", //数据字典的名称
"enumClassName": "com.power.doc.enums.OrderEnum", //数据字典枚举类名称
"codeField": "code",//数据字典字典码对应的字段名称
"descField": "desc"//数据字典对象的描述信息字典
}
],
"errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置
"title": "title",
"enumClassName": "com.power.doc.enums.ErrorCodeEnum", //错误码枚举类
"codeField": "code",//错误码的code码字段名称
"descField": "desc"//错误码的描述信息对应的字段名
}],
"revisionLogs": [ //设置文档变更记录，没有需求可以不设置
{
"version": "1.0", //文档版本号
"status": "update", //变更操作状态，一般为：创建、更新等
"author": "author", //文档变更作者
"remarks": "desc" //变更描述
}
],
"customResponseFields": [ //自定义添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释，非必须
{
"name": "code",//覆盖响应码字段
"desc": "响应代码",//覆盖响应码的字段注释
"value": "00000"//设置响应码的值
}
],
"apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染，非必须
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
}],
"requestHeaders": [ //设置请求头，没有需求可以不设置
{
"name": "token",
"type": "string",
"desc": "desc",
"required": false,
"since": "-"
}
],
"sourceCodePaths": [ //设置代码路径，默认加载src/main/java, 没有需求可以不设置
{
"path": "src/main/java",
"desc": "测试"
}
]
}
```
**注意：** 上面的json配置完全使用smart-doc的`ApiConfig`转化成json而来。因此项目配置也可以参考smart-doc的介绍。
### Generated document
#### Run plugin with maven command
```
//生成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
//生成postmanjson数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
```
**注意：** 尤其在window系统下，如果实际使用maven命令行执行文档生成，可能会出现乱码，因此需要在执行时指定`-Dfile.encoding=UTF-8`。
查看maven的编码
```
# mvn -version
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00)
Maven home: D:\ProgramFiles\maven\bin\..
Java version: 1.8.0_191, vendor: Oracle Corporation
Java home: D:\ProgramFiles\Java\jdk1.8.0_191\jre
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"
```
#### Run plugin in IDEA
当你使用Idea时，可以通过maven Helper插件选择生成何种文档。
### 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-maven-plugin/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-maven-plugin 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)登记（仅供开源用户参考）
## Contact
愿意参与构建smart-doc或者是需要交流问题可以加入qq群：
