update README_CN.md
This commit is contained in:
shalousun
parent
6778a4f6ad
commit
fd0a80c784
282
README_CN.md
282
README_CN.md
|
|
@ -14,7 +14,7 @@ Collection2.0+、OpenAPI 3.0+的文档。
|
|||
$\color{red}{你给我的star，胜过所有读过的诗—smart-doc}$
|
||||
|
||||
> 无论你是很有经验的大佬、还是刚入行的萌新。遇到使用疑惑时，我们希望你能仔细阅读smart-doc官方码云的wiki文档。我们将smart-doc及其插件的 每一个配置项和可能在日常中遇到的问题都整理到了文档中。仔细阅读文档就是对开源项目最大的支持。
|
||||
[wiki文档](https://gitee.com/smart-doc-team/smart-doc/wikis/HOME?sort_id=3127893)
|
||||
[wiki文档](https://smart-doc-group.github.io/#/zh-cn/)
|
||||
|
||||
## Features
|
||||
|
||||
|
|
@ -43,281 +43,6 @@ smart-doc + [Torna](http://torna.cn) 组成行业领先的文档生成和管理
|
|||
|
||||
> Torna是由smart-doc官方独家推动联合研发的企业级文档管理系统，因此smart-doc官方不会对接其它任何的外部文档管理系统，例如像showdoc、yapi 之类的对接请自定内部处理，也不要再给我们提其他文档系统对接的PR。我们核心是把smart-doc+Torna的这套方案打造好。
|
||||
|
||||
## Getting Started
|
||||
|
||||
smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/smart-doc-team/smart-doc-example-cn.git)。
|
||||
|
||||
```
|
||||
# git clone https://gitee.com/smart-doc-team/smart-doc-example-cn.git
|
||||
```
|
||||
你可以启动这个Spring Boot的项目，然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。
|
||||
|
||||
maven多模块项目请参考
|
||||
```
|
||||
# git clone https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module.git
|
||||
```
|
||||
### Add Maven Plugin
|
||||
|
||||
smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc-team/smart-doc-maven-plugin)
|
||||
和[Gradle插件](https://gitee.com/smart-doc-team/smart-doc-gradle-plugin)，
|
||||
你可以根据自己的构建工具来选择使用Maven插件或者是Gradle插件。
|
||||
|
||||
#### 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;参考如下-->
|
||||
<!--也可以支持正则式如：com.alibaba:.* -->
|
||||
<exclude>com.alibaba:fastjson</exclude>
|
||||
</excludes>
|
||||
<!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意-->
|
||||
<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
|
||||
<includes>
|
||||
<!--格式为：groupId:artifactId;参考如下-->
|
||||
<!--也可以支持正则式如：com.alibaba:.* -->
|
||||
<include>com.alibaba:fastjson</include>
|
||||
</includes>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
|
||||
<phase>compile</phase>
|
||||
<goals>
|
||||
<!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
|
||||
<goal>html</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
|
||||
在项目中添加创建一个`smart-doc.json`配置文件，插件读取这个配置来生成项目的文档， 这个配置内容实际上就是以前采用单元测试编写的`ApiConfig`转成json后的结果，因此关于配置项说明可以参考原来单元测试的配置。
|
||||
|
||||
**最小配置单元：**
|
||||
|
||||
```
|
||||
{
|
||||
"outPath": "D://md2" //指定文档的输出路径,相对路径时请用./开头，eg:./src/main/resources/static/doc
|
||||
}
|
||||
```
|
||||
|
||||
> 如果你想把html文档也打包到应用中一起访问，则建议你配置路径为：src/main/resources/static/doc
|
||||
|
||||
仅仅需要上面一行配置就能启动smart-doc-maven-plugin插件，根据自己项目情况更多详细的配置参考下面。
|
||||
**详细配置说明**
|
||||
|
||||
```
|
||||
{
|
||||
"serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
|
||||
"pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
|
||||
"isStrict": false, //是否开启严格模式
|
||||
"allInOne": true, //是否将文档合并到一个文件中，一般推荐为true
|
||||
"outPath": "D://md2", //指定文档的输出路径
|
||||
"coverOld": true, //是否覆盖旧的文件，主要用于mardown文件覆盖
|
||||
"createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
|
||||
"packageFilters": "",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
|
||||
"md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
|
||||
"style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
|
||||
"projectName": "smart-doc",//配置自己的项目名称
|
||||
"skipTransientField": true,//目前未实现
|
||||
"sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
|
||||
"showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
|
||||
"requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
|
||||
"responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
|
||||
"inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始
|
||||
"recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since 1.8.8版本开始
|
||||
"allInOneDocFileName":"index.html",//自定义设置输出文档名称, @since 1.9.0
|
||||
"requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
|
||||
"responseExample":"true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0
|
||||
"requestParamsTable": true, //是否将请求参数表展示在文档中，默认true，@since 2.2.5
|
||||
"responseParamsTable": true //是否将响应参数表展示在文档中, 默认true，@since 2.2.5
|
||||
"urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0
|
||||
"displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
|
||||
"appKey": "20201216788835306945118208",// torna平台对接appKey,, @since 2.0.9
|
||||
"appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
|
||||
"secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，@since 2.0.9
|
||||
"openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
|
||||
"debugEnvName":"测试环境", //torna环境名称
|
||||
"debugEnvUrl":"http://127.0.0.1",//推送torna配置接口服务地址
|
||||
"tornaDebug":false,//启用会推送日志
|
||||
"replace":true, // 推送文档到torna强制替换 @since 2.2.4
|
||||
"ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
|
||||
"org.springframework.ui.ModelMap"
|
||||
],
|
||||
"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", //文档版本号
|
||||
"revisionTime": "2020-12-31 10:30", //文档修订时间
|
||||
"status": "update", //变更操作状态，一般为：创建、更新等
|
||||
"author": "author", //文档变更作者
|
||||
"remarks": "desc" //变更描述
|
||||
}
|
||||
],
|
||||
"customResponseFields": [{ //自定义添加字段和注释，一般用户处理第三方jar包库，非必须
|
||||
"name": "code",//覆盖响应码字段
|
||||
"desc": "响应代码",//覆盖响应码的字段注释
|
||||
"ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
|
||||
"ignore":true, //设置true会被自动忽略掉不会出现在文档中
|
||||
"value": "00000"//设置响应码的值
|
||||
}],
|
||||
"customRequestFields": [{ //自定义请求体的注释，@since 2.1.3，非必须
|
||||
"name":"code", //属性名
|
||||
"desc":"状态码", //描述
|
||||
"ownerClassName":"com.xxx.constant.entity.Result", //属性对应的类全路径
|
||||
"value":"200", //默认值或者mock值
|
||||
"required":true, //是否必填
|
||||
"ignore":false //是否忽略
|
||||
}],
|
||||
"requestHeaders": [{ //设置请求头，没有需求可以不设置
|
||||
"name": "token",//请求头名称
|
||||
"type": "string",//请求头类型
|
||||
"desc": "desc",//请求头描述信息
|
||||
"value":"token请求头的值",//不设置默认null
|
||||
"required": false,//是否必须
|
||||
"since": "-",//什么版本添加的改请求头
|
||||
"pathPatterns": "/app/test/**",//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
|
||||
"excludePathPatterns":"/app/page/**"//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
|
||||
},{
|
||||
"name": "appkey",//请求头
|
||||
"type": "string",//请求头类型
|
||||
"desc": "desc",//请求头描述信息
|
||||
"value":"appkey请求头的值",//不设置默认null
|
||||
"required": false,//是否必须
|
||||
"pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头，多个正则用分号隔开
|
||||
"since": "-"//什么版本添加的改请求头
|
||||
}],
|
||||
"requestParams": [ //公共请求参数(通过拦截器处理的场景)，@since 2.2.3,没有需求请不要设置
|
||||
{
|
||||
"name": "configPathParam",//请求头名称
|
||||
"type": "string",//请求头类型
|
||||
"desc": "desc",//请求头描述信息
|
||||
"paramIn": "path",
|
||||
"value":"testPath",//不设置默认null
|
||||
"required": false,//是否必须
|
||||
"since": "-",//什么版本添加的改请求头
|
||||
"pathPatterns": "*",//正则表达式过滤请求头
|
||||
"excludePathPatterns":"/app/page/**" //参考请求头中的用法
|
||||
},
|
||||
{
|
||||
"name": "configQueryParam",//请求头名称
|
||||
"type": "string",//请求头类型
|
||||
"desc": "desc",//请求头描述信息
|
||||
"paramIn": "query",
|
||||
"value":"testQuery",//不设置默认null
|
||||
"required": false,//是否必须
|
||||
"since": "-",//什么版本添加的改请求头
|
||||
"pathPatterns": "*",//正则表达式过滤请求头
|
||||
"excludePathPatterns":"/app/page/**"
|
||||
}
|
||||
],
|
||||
"rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
|
||||
"artifactId":"SpringBoot2-Dubbo-Api",
|
||||
"groupId":"com.demo",
|
||||
"version":"1.0.0"
|
||||
}],
|
||||
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置，用于方便集成方可以快速集成
|
||||
"apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染，非必须
|
||||
"className": "org.springframework.data.domain.Pageable",
|
||||
"replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
|
||||
}],
|
||||
"apiConstants": [{//从1.8.9开始配置自己的常量类，smart-doc在解析到常量时自动替换为具体的值，非必须
|
||||
"constantsClassName": "com.power.doc.constants.RequestParamConstant" //引用常量时需要用RequestParamConstant.xxx才能被正确解析
|
||||
}],
|
||||
"responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
|
||||
"className":"com.power.common.model.CommonResult" //通用响应体
|
||||
},
|
||||
"requestBodyAdvice":{ ////自smart-doc 2.1.4 起，支持设置RequestBodyAdvice统一请求包装类，非必须
|
||||
"className":"com.power.common.model.CommonResult"
|
||||
},
|
||||
"groups": [ // @since 2.2.5, 对不同的controller进行分组
|
||||
{
|
||||
"name": "测试分组",
|
||||
"apis": "com.power.doc.controller.app.*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
>上面的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
|
||||
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
|
||||
// 生成文档推送到Torna平台
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest
|
||||
|
||||
// Apache Dubbo RPC文档
|
||||
// Generate html
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
|
||||
// Generate markdown
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
|
||||
// Generate adoc
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc
|
||||
|
||||
// 生成dubbo接口文档推送到torna
|
||||
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc
|
||||
```
|
||||
|
||||
**注意：** 尤其在window系统下，如果实际使用Maven命令行执行文档生成，可能会出现乱码，因此需要在执行时指定`-Dfile.encoding=UTF-8`。
|
||||
|
||||
#### Use in IDEA
|
||||
|
||||
|
||||
|
||||
### Use gradle plugin
|
||||
|
||||
如果你使用Gradle来构建项目，你可以参考Gradle插件的使用文档来集成，
|
||||
[smart-doc-gradle-plugin](https://gitee.com/smart-doc-team/smart-doc-gradle-plugin/blob/master/README_CN.md)
|
||||
|
||||
### Use Junit Test
|
||||
|
||||
从smart-doc 1.7.9开始，官方提供了Maven插件，使用smart-doc的Maven插件后不再需要创建单元测试。
|
||||
[单元测试生成文档](https://gitee.com/smart-doc-team/smart-doc/wikis/单元测试集成smart-doc?sort_id=1990284)
|
||||
|
||||
> 单元测试集成存在很多局限性: <br/>1. 对于多模块项目源码注释很麻烦，也不符合正常开发团队的开发协作。<br/>2. 不方便与CI工具集成
|
||||
|
||||
### Generated document example
|
||||
|
||||
[点击查看文档生成文档效果图](https://gitee.com/smart-doc-team/smart-doc/wikis/文档效果图?sort_id=1652819)
|
||||
|
||||
## Building
|
||||
|
||||
如果你需要自己构建smart-doc，那可以使用下面命令，构建需要依赖Java 1.8。
|
||||
|
|
@ -330,11 +55,6 @@ mvn clean install -Dmaven.test.skip=true
|
|||
|
||||
- Jakarta RS-API 2.x
|
||||
|
||||
## Other reference
|
||||
|
||||
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
|
||||
- [smart-doc官方wiki](https://gitee.com/smart-doc-team/smart-doc/wikis/Home?sort_id=1652800)
|
||||
|
||||
## License
|
||||
|
||||
smart-doc is under the Apache 2.0 license. See
|
||||
|
|
|
|||
Loading…
Reference in New Issue