smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,还支持接口在线调试。
不用依赖任何注解,不会像swagger一样需要写很多繁琐的注解
使用教程
在pom文件中引入插件
<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>2.1.3</version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>测试</projectName> <!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库加载不到导致报错,这时请使用excludes排除掉--> <excludes> <!--格式为:groupId:artifactId;参考如下--> <!--1.0.7版本开始你还可以用正则匹配排除,如:poi.* --> <exclude>com.alibaba:fastjson</exclude> </excludes> <!--自1.0.8版本开始,插件提供includes支持--> <!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效率,因此你可以使用includes来让插件加载你配置的组件--> <includes> <!--格式为:groupId:artifactId;参考如下--> <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>
在resource下添加文件smart-doc.json
{ "serverUrl": "http://127.0.0.1:7788/cq-web", //设置服务器地址,非必须 "isStrict": false, //是否开启严格模式 "allInOne": true, //是否将文档合并到一个文件中,一般推荐为true "outPath": "src/main/webapp/doc", //指定文档的输出路径 "coverOld": true, //是否覆盖旧的文件,主要用于mardown文件覆盖 "packageFilters": "",//controller包过滤,多个包用英文逗号隔开 "style":"xt256", //基于highlight.js的代码高亮设置,喜欢配色统一简洁的同学可以不设置 "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面,仅在AllInOne模式中起作用。 "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用 "projectName": "贵州省煤炭及煤炭清洁转化产品大数据平台接口文档",//配置自己的项目名称 "skipTransientField": true,//目前未实现 "showAuthor":true,//是否显示接口作者名称,默认是true,不想显示可关闭 "requestFieldToUnderline":false, //自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7 版本开始 "responseFieldToUnderline":false,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7 版本开始 "inlineEnum":true,//设置为true会将枚举详情展示到参数表中,默认关闭,//@since 1.8.8版本开始 "recursionLimit":7,//设置允许递归执行的次数用于避免栈溢出,默认是7,正常为3次以内,//@since 1.8.8版本开始 "displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名,@since 1.9.6 // "urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0 "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,和serverUrl会有冲突,设置serverUrl则可以不设置该选项 "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", //错误码枚举类,如果是枚举是在一个类中定义则用$链接类BaseErrorCode$Common "codeField": "code",//错误码的code码字段名称 "descField": "message"//错误码的描述信息对应的字段名 }], "revisionLogs": [ //设置文档变更记录,没有需求可以不设置 { "version": "1.0", //文档版本号 "revisionTime":"2020-12-31 10:30",//文档修订时间 "status": "update", //变更操作状态,一般为:创建、更新等 "author": "author", //文档变更作者 "remarks": "desc" //变更描述 } ], "customResponseFields": [ //自定义添加字段和注释,api-doc后期遇到同名字段则直接给相应字段加注释,非必须 { "name": "code",//覆盖响应码字段 "desc": "响应代码",//覆盖响应码的字段注释 "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名 "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", // "required": false, // "value":"55", // "since": "-" // } // ], "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在解析到常量时自动替换为具体的值,如:http://localhost:8080/testConstants/+ApiVersion.VERSION中的ApiVersion.VERSION会被替换 "constantsClassName": "com.power.doc.constants.RequestParamConstant" }], "responseBodyAdvice":{ //自smart-doc 1.9.8起,ResponseBodyAdvice统一返回设置,可用ignoreResponseBodyAdvice tag来忽略 "className":"com.power.common.model.CommonResult" //通用响应体 }, "sourceCodePaths": [ //设置代码路径,smart-doc默认会自动加载src/main/java, 没有需求可以不设置 1.0.0以后版本此配置不再生效 { "path": "src/main/java", "desc": "测试" } ] }
配置后 maven中会出现smart-doc的插件 点直接运行就可以
将生成的文档放在项目中 可以随项目启动一起访问