diff --git a/.gitee/ISSUE_TEMPLATE.zh-CN.md b/.gitee/ISSUE_TEMPLATE.zh-CN.md index b3c984e..3379b48 100644 --- a/.gitee/ISSUE_TEMPLATE.zh-CN.md +++ b/.gitee/ISSUE_TEMPLATE.zh-CN.md @@ -1,4 +1,5 @@ ### 您的使用环境(必填,不填写官方直接关闭issue) + maven和gradle版本信息根据个人使用情况填写 - maven版本号：xxx @@ -7,17 +8,16 @@ maven和gradle版本信息根据个人使用情况填写 - smart-doc-gradle-plugin版本号：xxx ### 该问题是怎么引起的(如果最新版本已经修复的，会直接关闭)？ + 编写关于整个issue描述前注意阅读下面的注意事项，尤其是萌新的同学： + 1. 提issue时请认真阅读官方的wiki文档及相关配置说明，少给开源软件提无效的issue是一个IT从业人的专业素养。 -2. 提某些简单使用问题的issue时请先思考，smart-doc从18年开源以来已经有很多企业使用，码云的指数也很高。 - 很多问题都已解决，开源玩具是走不进企业的，这已经是一个偏向成熟的软件了。请仔细阅读文档找到相关解决方法。 -3. 当你提出问题时尽量思考你的描述信息能否让官方人员复现。不要随便扔个报错信息出来就把开源人当神仙了。 - smart-doc是一款很依赖你本地环境和代码数据的工具。官方人员并没有你的代码数据和模拟相同环境。 - 因此建议你先自己debug，官方的wiki也有详细的介绍怎么去debug smart-doc或smart-doc的相关插件， - 文档把调试步骤都写了，不要说你不懂。 - - 最后、祝你使用愉快！ +2. 提某些简单使用问题的issue时请先思考，smart-doc从18年开源以来已经有很多企业使用，码云的指数也很高。 很多问题都已解决，开源玩具是走不进企业的，这已经是一个偏向成熟的软件了。请仔细阅读文档找到相关解决方法。 +3. 当你提出问题时尽量思考你的描述信息能否让官方人员复现。不要随便扔个报错信息出来就把开源人当神仙了。 smart-doc是一款很依赖你本地环境和代码数据的工具。官方人员并没有你的代码数据和模拟相同环境。 + 因此建议你先自己debug，官方的wiki也有详细的介绍怎么去debug smart-doc或smart-doc的相关插件， 文档把调试步骤都写了，不要说你不懂。 + +最后、祝你使用愉快！ + ### 重现步骤(必填,不填写官方直接关闭issue) - ### 报错信息(必填,不填写官方直接关闭issue) \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index da09d08..830afe8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,37 +1,43 @@ --- -name: Bug report 🐞 -about: Create a report to help us improve -title: '' -labels: bug -assignees: '' +name: Bug report 🐞 about: Create a report to help us improve title: '' +labels: bug assignees: '' --- + ## Your Environment(您的使用环境) + + * smart-doc version: * plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin): * build tool version(maven or gradle): ## Expected Behavior(您期望的结果) + ## Current Behavior(当前结果) + ## Possible Solution(bug解决建议) + ## Steps to Reproduce (Bug产生步骤，请尽量提供用例代码) + + 1. 2. 3. 4. ## Context(Bug影响描述) + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 742ca6e..bfffa7e 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,11 +1,15 @@ --- -name: Feature Request 💡 -about: Suggest a new idea for the project. -labels: enhancement +name: Feature Request 💡 about: Suggest a new idea for the project. labels: enhancement --- + ## Summary(关于这个pr的描述) + Brief explanation of the feature. + ### Basic example(pr的用例) + If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable. + ### Motivation(提出这个pr目的) + Why are we doing this? What use cases does it support? What is the expected outcome? \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 9eebea2..199eb48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,27 +1,37 @@ ## smart-doc版本 + #### 版本号：2.1.8 + - 更新日期: 2020-05-17 - 更新内容： 1. 修复推送接口到torna丢失部分mock值的问题。 2. 修复在参数注释中配置类替换时将非类名解析成类名的bug 。 3. 支持父类上加@RestController注解的子类能够被识别和扫描 + #### 版本号：2.1.7 + - 更新日期: 2020-05-12 - 更新内容： 1. 添加推送接口作者信息到torna数据错误的bug。 2. 修复空参数curl命令多余？号问题，github 。 + #### 版本号：2.1.6 + - 更新日期: 2020-05-10 - 更新内容： 1. 修复不允许List中放文件上传对象错误的bug。 2. 添加推送接口作者信息到torna,通过配置author设置推送人，不配置默认为计算机用户名。 3. 添加推送queryParams参数到torna(需要使用torna 1.6.0+) + #### 版本号：2.1.5 + - 更新日期: 2020-05-05 - 更新内容： 1. 修复requestBodyAdvice请求样例丢之。 2. 添加dubbo文档到torna的推送。 + #### 版本号：2.1.4 + - 更新日期: 2020-04-24 - 更新内容： 1. 修复Controller继承时，父类的Mapping未继承的问题。 @@ -31,7 +41,9 @@ 5. 新增requestBodyAdvice支持，可以实现请求参数包装。 6. 修复泛型为List数据时，类型为object问题。 7. 修复customFiled为继承参数时配置失效问题。 + #### 版本号：2.1.3 + - 更新日期: 2020-04-11 - 更新内容： 1. 增强对文件上传的支持。 @@ -39,17 +51,23 @@ 3. 修复往torna推送漏掉pathParams的问题。 4. 修改debug测试页面，支持post表单请求 5. 修改表单请求对象中枚举字段默认值错误的bug + #### 版本号：2.1.2 + - 更新日期: 2020-03-29 - 更新内容： 1. 修复Map嵌套在某些结构体中栈溢出问题，gitee #I3CCLY。 2. 修复Torna数据推送问题。 + #### 版本号：2.1.1 + - 更新日期: 2020-03-24 - 更新内容： 1. 修复Map嵌套在某些结构体中栈溢出问题，gitee #I3CCLY。 2. 修复Torna数据推送问题。 + #### 版本号：2.1.0 + - 更新日期: 2020-03-21 - 更新内容： 1. 导出的postman的url资源下添加缺失的protocol。 @@ -57,19 +75,25 @@ 3. 增加了自动生成版本记录的功能。 4. 修改torna推送的bug。 5. 支持旧的SpringMVC项目的url后缀，新项目不建议加什么破玩意后缀。 + #### 版本号：2.0.9 + - 更新日期: 2020-03-12 - 更新内容： 1. 支持UUID和ZonedDateTime字段类型，#89。 2. 对map参数增加开关来兼容旧项目，还是不建议使用map参数。 3. 完成和Torna的对接。 + #### 版本号：2.0.8 + - 更新日期: 2020-02-26 - 更新内容： 1. 修复文件上传的参数丢失的注释。 2. 修复2.0.7新增忽略接口方法后解析父类字段缺失注释bug。 3. 修改byte类型的转换，将过去的string转为int8。 + #### 版本号：2.0.7 + - 更新日期: 2020-01-30 - 更新内容： 1. 修复postman的url中不附加的context-path的问题。 @@ -77,24 +101,32 @@ 3. 添加对默认接口实现中get方法重写忽略的能力解析。 4. 修改数组、map等字段类型的自定义mock值显示错误问题。 5. 修复对mapping中headers的处理。 + #### 版本号：2.0.6 + - 更新日期: 2020-01-15 - 更新内容： 1. 修复带正则的path路径参数在postman中用例问题。 2. 增强对祖传不良代码的分析兼容。 + #### 版本号：2.0.5 + - 更新日期: 2020-01-09 - 更新内容： 1. 修复集合类无泛型参数作为入参出参时的数组越界。 2. 修复新开tab访问的url拼接问题。 + #### 版本号：2.0.3-2.0.4 + - 更新日期: 2020-01-01 - 更新内容： 1. 修改页面的错误列表标题显示。 2. 修改debug页面curl header语法错误。 3. 修改debug页面json参数输入框，允许粘贴小段文本。 4. 解决使用dubbo 2.7+，在provider中生成文档出错问题 github #77. + #### 版本号：2.0.2 + - 更新日期: 2020-02-27 - 更新内容： 1. 修改创建openapi时的空指针异常。 @@ -109,7 +141,9 @@ 10. 添加对集合字段中枚举的处理。 11. 枚举序列化支持优化。 12. 调试页面新增Highlight支持。 + #### 版本号：2.0.1 + - 更新日期: 2020-12-20 - 更新内容： 1. debug调试页面支持文件上传。 @@ -117,7 +151,9 @@ 3. debug页面完全支持文件下载测试。 4. 所有html的文档支持接口目录搜索。 5. 剔除flexmark依赖，旧的非allInOne模板删除，统一h5文档样式。 + #### 版本号：2.0.0 + - 更新日期: 2020-12-13 - 更新内容： 1. 优化了文档的显示，将query和path单独提出来做了展示 @@ -126,12 +162,16 @@ 4. 添加分组支持group。 5. 修改mock的一些bug和增强使用 6. 支出创建debug页面 + #### 版本号：1.9.9.1 + - 更新日期: 2020-11-23 - 更新内容： 1. 这是一个紧急修改版本。 2. 解决1.9.9版本controller中存在非路径映射方法时的错误。 + #### 版本号：1.9.9 + - 更新日期: 2020-11-23 - 更新内容： 1. 修改1.9.8启用严格检查注释模式下的bug。 @@ -141,7 +181,9 @@ 5. 增加对@RequestMapping注解的path属性的解析支持 6. 修复postman中formdata表单不显示描述信息的问题 7. html5 allInOne模板支持代码高亮。 + #### 版本号：1.9.8 + - 更新日期: 2020-11-10 - 更新内容： 1. 忽略Class对象的解析。 @@ -150,7 +192,9 @@ 4. 修改模拟值生成错误。 5. 支持ResponseBodyAdvice通用接口响应包装设置。 6. 修复类同时继承和基类和实现接口中可能出现字段重复的bug。 + #### 版本号：1.9.7 + - 更新日期: 2020-10-24 - 更新内容： 1. 修复restful接口泛型中使用?时的解析错误。 @@ -158,7 +202,9 @@ 3. 对rest query参数自动添加描述，增加可读性。 4. support ali dubbo,#I22CF7 . 5. support @RequestMapping headers. + #### 版本号：1.9.6 + - 更新日期: 2020-10-09 - 更新内容： 1. 修复RequestParam 解析错误。 @@ -167,19 +213,25 @@ 4. 增加泛型实际类型的显示开关控制。 5. 修复类继承一个泛型类时的解析错误。 6. 优化smart-doc maven插件，提升用户在多模块下的使用体验。 + #### 版本号：1.9.5 + - 更新日期: 2020-09-19 - 更新内容： 1. 接口参数无注解时将required设置为false。 2. 修改html自适应。 + #### 版本号：1.9.4 + - 更新日期: 2020-09-06 - 更新内容： 1. 添加order tag支持对api做排序。 2. 优化一些重复的代码。 3. 修改基础url中使用常量出现空格的问题。 4. 添加生成yapi文件的功能。 + #### 版本号：1.9.3 + - 更新日期: 2020-08-30 - 更新内容： 1. 修复Get请求用例参数值被去空格问题。 @@ -187,7 +239,9 @@ 3. 修复非allInOne模板使用渲染错误。 4. 修复一些泛型例子解析错误bug。 5. 优化MultipartFile文件上传参数处理，不对该参数进行展开分析。 + #### 版本号：1.9.2 + - 更新日期: 2020-08-23 - 更新内容： 1. 修改前面版本修改引发的普通jsr 303验证解析错误问题。 @@ -197,14 +251,18 @@ 5. 新增对Open Api 3.0的支持。 6. 修改字典表空时内部发生空指针的问题。 7. 优化curl用例，增加请求头。 + #### 版本号：1.9.1 + - 更新日期: 2020-08-02 - 更新内容： 1. 修改进去版本更新导致的泛型解析问题。 2. 修改1.8.9版本修改后带来的dubbo接口文档显示问题 2. 修改smart-doc-maven-plugin生成dubbo文档时缺乏配置文件错误问题。 3. 修改gradle插件的对多模块的支持。 + #### 版本号：1.9.0 + - 更新日期: 2020-07-19 - 更新内容： 1. 修改dubbo html依赖部分错乱问题。 @@ -212,14 +270,18 @@ 3. 添加请求和响应示例的开关配置项。 4. 修改使用JSR303参数校验时，默认分组验证被忽略问题。 5. 修改jackson JsonIgnore注解在参数对象中不生效的问题。 + #### 版本号：1.8.9 + - 更新日期: 2020-07-05 - 更新内容： 1. 修改git #38。 2. 修改gitee #I1LBKO。 3. 修改fix #39多泛型解析顺序问题。 4. 优化支持gitee #I1IQKY常量解析需求 + #### 版本号：1.8.8 + - 更新日期: 2020-06-21 - 更新内容： 1. 修改忽略对LinkedHashMap的解析，gitee #I1JI5W。 @@ -228,7 +290,9 @@ 4. 优化枚举参数展示，支持自定义控制显示。 5. 添加Feign的支持。 6. 优化递归执行，对外提供递归次数限制。 + #### 版本号：1.8.7 + - 更新日期: 2020-06-01 - 更新内容： 1. 增加对java接口的分析，例如Jpa的分页Page类。 @@ -238,205 +302,260 @@ 5. maven插件和gradle插件提供includes支持，方便自行配置加载第三方库。 6. fix #32. 7. 增加文档接口根据接口标题排序功能。 + #### 版本号：1.8.6 + - 更新日期: 2020-05-09 - 更新内容： - 1. 增加localTime支持[gitee #I1F7CW](https://gitee.com/sunyurepository/smart-doc/issues/I1F7CW)。 - 2. 优化smart-doc导入Postman collection时的header问题[gitee #I1EX42](https://gitee.com/sunyurepository/smart-doc/issues/I1EX42) + 1. 增加localTime支持[gitee #I1F7CW](https://gitee.com/sunyurepository/smart-doc/issues/I1F7CW)。 + 2. 优化smart-doc导入Postman + collection时的header问题[gitee #I1EX42](https://gitee.com/sunyurepository/smart-doc/issues/I1EX42) 3. 优化smart-doc-maven-plugin加载source的过滤，支持使用通配符来过滤。 4. 首次发布gradle插件，发布smart-doc-gradle-plugin插件， 5. 修复通用泛型解析出错[git #28](https://github.com/smart-doc-group/smart-doc/issues/28)。 + #### 版本号：1.8.5 + - 更新日期: 2020-04-19 - 更新内容： - 1. maven插件错误码列表导出bug[git #I1EHXA](https://gitee.com/sunyurepository/smart-doc/issues/I1EHXA)。 - 2. 增加@PatchMapping支持[gitee #I1EDRF](https://gitee.com/sunyurepository/smart-doc/issues/I1EDRF) - 3. 解决javadoc包含重复tag生成文档报错[gitee #I1ENNM](https://gitee.com/sunyurepository/smart-doc/issues/I1ENNM)。 + 1. maven插件错误码列表导出bug[git #I1EHXA](https://gitee.com/sunyurepository/smart-doc/issues/I1EHXA)。 + 2. 增加@PatchMapping支持[gitee #I1EDRF](https://gitee.com/sunyurepository/smart-doc/issues/I1EDRF) + 3. 解决javadoc包含重复tag生成文档报错[gitee #I1ENNM](https://gitee.com/sunyurepository/smart-doc/issues/I1ENNM)。 4. 修改当请求参数为泛型时数据解析错误问题。 5. 修复分组验证空指针问题，不对返回对象做分组验证处理。 6. 优化smart-doc-maven-plugin对多级maven项目的加载。 7. 支持请求参数对象替换成另外的对象来渲染文档 + #### 版本号：1.8.4 + - 更新日期: 2020-03-30 - 更新内容： - 1. Controller新增时候@ignore tag,可适应该tag忽略不需要生成文档的controller[git #24](https://github.com/smart-doc-group/smart-doc/issues/24)。 - 2. 参数中包含 HttpSession时smart-doc卡主，[gitee #I1CA9M](https://gitee.com/sunyurepository/smart-doc/issues/I1CA9M) - 3. 解决一些复杂分组场景smart-doc报错的问题[gitee #I1CPSM](https://gitee.com/sunyurepository/smart-doc/issues/I1CPSM)。 + 1. Controller新增时候@ignore + tag,可适应该tag忽略不需要生成文档的controller[git #24](https://github.com/smart-doc-group/smart-doc/issues/24)。 + 2. 参数中包含 HttpSession时smart-doc卡主，[gitee #I1CA9M](https://gitee.com/sunyurepository/smart-doc/issues/I1CA9M) + 3. 解决一些复杂分组场景smart-doc报错的问题[gitee #I1CPSM](https://gitee.com/sunyurepository/smart-doc/issues/I1CPSM)。 4. 解决smart-doc-maven-plugin插件读取配置乱码问题。 + #### 版本号：1.8.3 + - 更新日期: 2020-03-21 - 更新内容： - 1. 增加从接口方法getter或者setter方法中读取注释。 - 2. 修改smart-doc默认编码为utf-8，解决生成文档乱码问题。 - 3. 增加对代码中@author tag的支持，支持多作者。 + 1. 增加从接口方法getter或者setter方法中读取注释。 + 2. 修改smart-doc默认编码为utf-8，解决生成文档乱码问题。 + 3. 增加对代码中@author tag的支持，支持多作者。 + #### 版本号：1.8.2 + - 更新日期: 2020-03-13 - 更新内容： - 1. 修改gitee #I19IYW 。 - 2. 修改文档模板中的title设置错误。 - 3. 修改gitee #I191EO - 4. 支持@Validated 分组 + 1. 修改gitee #I19IYW 。 + 2. 修改文档模板中的title设置错误。 + 3. 修改gitee #I191EO + 4. 支持@Validated 分组 + #### 版本号：1.8.1 + - 更新日期: 2020-01-22 - 更新内容： - 1. 增加对接口get方法的分析。 - 2. 增加对第三方jar中list泛型数据的解析。 - 3. 删除原来冗长的SourceBuilder代码。 - 4. 修改AdocDocBuilder、HtmlApiDocBuilder、ApiDocBuilder的方法名规范化，单元测试的升级需要做小部分变更。 - 5. 修改1.8.0重构后的请求示例将header放入普通参数的bug。 - 6. 修改参数加上@Validated注解后，文档里没有该参数信息的bug。 - 7. 新增@Deprecated标注接口的支持(使用line through完成样式标记) + 1. 增加对接口get方法的分析。 + 2. 增加对第三方jar中list泛型数据的解析。 + 3. 删除原来冗长的SourceBuilder代码。 + 4. 修改AdocDocBuilder、HtmlApiDocBuilder、ApiDocBuilder的方法名规范化，单元测试的升级需要做小部分变更。 + 5. 修改1.8.0重构后的请求示例将header放入普通参数的bug。 + 6. 修改参数加上@Validated注解后，文档里没有该参数信息的bug。 + 7. 新增@Deprecated标注接口的支持(使用line through完成样式标记) + #### 版本号：1.8.0 + - 更新日期: 2020-01-01 - 更新内容： - 1. 修改参数上多个验证注解不支持的问题。 - 2. 修改支持上传文件参数不列举到文档的问题。 - 3. 新增ApiDataBuilder用于获取smart-doc生成的文档数据，包含header、字典、错误码等。 - 4. 合并fork分支的github book html5模板，新增搜索和锚点。 - 5. 新增自定义@mock tag用于指定生成文档的字段值，@param 的参数注释增加mock值的功能(@param name 姓名|张三) - 6. 重点：smart-doc的maven插件smart-doc-maven-plugin增强对maven标准项目的支持。 - 7. 全面支持spring的表单参数绑定解析。 - 8. postman json生成支持所有参数自动回填。再也不用自己建参数了。 - 9. 优化对实体类中枚举字段的支持。 - 10. 增加对实体中静态常量常量字段的过滤。 + 1. 修改参数上多个验证注解不支持的问题。 + 2. 修改支持上传文件参数不列举到文档的问题。 + 3. 新增ApiDataBuilder用于获取smart-doc生成的文档数据，包含header、字典、错误码等。 + 4. 合并fork分支的github book html5模板，新增搜索和锚点。 + 5. 新增自定义@mock tag用于指定生成文档的字段值，@param 的参数注释增加mock值的功能(@param name 姓名|张三) + 6. 重点：smart-doc的maven插件smart-doc-maven-plugin增强对maven标准项目的支持。 + 7. 全面支持spring的表单参数绑定解析。 + 8. postman json生成支持所有参数自动回填。再也不用自己建参数了。 + 9. 优化对实体类中枚举字段的支持。 + 10. 增加对实体中静态常量常量字段的过滤。 + #### 版本号：1.7.9 + - 更新日期: 2019-12-16 - 更新内容： - 1. 修改request请求参数中嵌套对象不能解析的bug，参考gitee #I16AN2. - 2. controller参数是数组时添加@PathVariable注解会报空指针,参考gitee #I16F6G - 3. 新增ApiDataBuilder用于获取smart-doc生成的文档数据，包含header、字典、错误码等。 - 4. 修改github #9 文档错误bug. - 5. 新增接口的@author展示，方法从文档中查到找到接口负责人，生成文档可以选择关闭显示。 - 6. 重点：smart-doc的maven插件smart-doc-maven-plugin 1.0.0版本发布。 + 1. 修改request请求参数中嵌套对象不能解析的bug，参考gitee #I16AN2. + 2. controller参数是数组时添加@PathVariable注解会报空指针,参考gitee #I16F6G + 3. 新增ApiDataBuilder用于获取smart-doc生成的文档数据，包含header、字典、错误码等。 + 4. 修改github #9 文档错误bug. + 5. 新增接口的@author展示，方法从文档中查到找到接口负责人，生成文档可以选择关闭显示。 + 6. 重点：smart-doc的maven插件smart-doc-maven-plugin 1.0.0版本发布。 + #### 版本号：1.7.8 + - 更新日期: 2019-12-02 - 更新内容： - 1. 修改Spring Controller使用非Spring Web注解时生成的响应示例出错的bug。 - 2. 修改使用mybatis-plus实体继承Model对象时将log字段输出到文档的问题。 - 3. 添加对transient修饰字段文档输出开关，默认不输出。 - 4. html文档添加项目名称显示 - 5. 修改github #4 泛型中Void类型解析死循环 - 6. 修改github #5 简单枚举参数解析空指针异常 - 7. 添加导出PostMan json数据 + 1. 修改Spring Controller使用非Spring Web注解时生成的响应示例出错的bug。 + 2. 修改使用mybatis-plus实体继承Model对象时将log字段输出到文档的问题。 + 3. 添加对transient修饰字段文档输出开关，默认不输出。 + 4. html文档添加项目名称显示 + 5. 修改github #4 泛型中Void类型解析死循环 + 6. 修改github #5 简单枚举参数解析空指针异常 + 7. 添加导出PostMan json数据 + #### 版本号：1.7.7 + - 更新日期：2019-11-18 - 更新内容： - 1. 修改timestamp类型字段创建json示例错误bug。 - 2. fix #I1545A 单接口多路径bug。 - 3. 修改部分url生成部署空格问题。 - 4. 优化对java.util.concurrent.ConcurrentMap的解析。 + 1. 修改timestamp类型字段创建json示例错误bug。 + 2. fix #I1545A 单接口多路径bug。 + 3. 修改部分url生成部署空格问题。 + 4. 优化对java.util.concurrent.ConcurrentMap的解析。 + #### 版本号：1.7.6 + - 更新日期：2019-11-13 - 更新内容： - 1. fix #I14PT5 header重复渲染到文档 - 2. fix #I14MV7 不设置dataDictionaries出现空指针错误 - 3. 增加请求参数枚举字段解析(试用功能) + 1. fix #I14PT5 header重复渲染到文档 + 2. fix #I14MV7 不设置dataDictionaries出现空指针错误 + 3. 增加请求参数枚举字段解析(试用功能) + #### 版本号：1.7.5 + - 更新日期：2019-11-06 - 更新内容： - 1. 优化文档中错误列表的标题，可根据语言环境变化显示中文或因为。 - 2. 解决项目外jar中内部类生成文档错误的bug。 - 3. 支持环形依赖分析。只要你敢写！ - 4. 修改使用SpringMvc或者SpringBoot上传时接口的Content-Type显示错误。 - 5. 支持设置项目作为markdown的一级标题。 - 6. 修改方法注释相同引起的html链接跳转错误。 - 7. 添加生成AllInOne的覆盖配置项，默认自动加版本号不覆盖。 - 8. 新增枚举字典码导出到文档的功能。 + 1. 优化文档中错误列表的标题，可根据语言环境变化显示中文或因为。 + 2. 解决项目外jar中内部类生成文档错误的bug。 + 3. 支持环形依赖分析。只要你敢写！ + 4. 修改使用SpringMvc或者SpringBoot上传时接口的Content-Type显示错误。 + 5. 支持设置项目作为markdown的一级标题。 + 6. 修改方法注释相同引起的html链接跳转错误。 + 7. 添加生成AllInOne的覆盖配置项，默认自动加版本号不覆盖。 + 8. 新增枚举字典码导出到文档的功能。 + #### 版本号：1.7.4 + - 更新日期：2019-10-29 - 更新内容： - 1. 修改gitee上bug #I1426C。 - 2. 修改gitee上bug #I13ZAL,1.7.0~1.7.3 结构优化后产生的bug，建议用户升级。 - 3. 修改gitee上bug #I13U4C。 - 4. 修改设置中文语言环境(默认中文)下错误码列表title显示英文的问题。 - 5. 优化AllInOne的markdown展示，生成时带上自动产生的序号。 + 1. 修改gitee上bug #I1426C。 + 2. 修改gitee上bug #I13ZAL,1.7.0~1.7.3 结构优化后产生的bug，建议用户升级。 + 3. 修改gitee上bug #I13U4C。 + 4. 修改设置中文语言环境(默认中文)下错误码列表title显示英文的问题。 + 5. 优化AllInOne的markdown展示，生成时带上自动产生的序号。 + #### 版本号：1.7.3 + - 更新日期：2019-10-24 - 更新内容： - 1. 优化html5模板左侧文档目录展示，能够展开和收缩。 - 2. 修改gitee上bug #I13R3K。 - 3. 修改gitee上bug #I13NR1。 - 4. 开放的文档数据获取接口添加返回方法的唯一id和方法名称，方便一些企业自己做对接。 + 1. 优化html5模板左侧文档目录展示，能够展开和收缩。 + 2. 修改gitee上bug #I13R3K。 + 3. 修改gitee上bug #I13NR1。 + 4. 开放的文档数据获取接口添加返回方法的唯一id和方法名称，方便一些企业自己做对接。 + #### 版本号：1.7.2 + - 更新日期：2019-10-19 - 更新内容： - 1. 优化注释换行\n\r问题，依赖common-util 1.8.7。 - 2. 修改gitee上bug #I135PG、#I13NR1。 - 3. 添加@requestHeader注解的支持，文档自定将参数绑定到请求头列表中。 - 4. 增加javadoc apiNote tag的支持。 - 5. 解决扫描分析controller中private方法的问题。 - 6. 添加支持@RequestParam注解重写参数名和设置默认值的文档解析。 - 7. 支持使用@PostMapping和@PutMapping请求自定义注解接收单个json参数场景下生成json请求实例。 - 8. 新增对Spring ResponseEntity的解析。 - 9. 增加内部类返回结构解析。 - 10. 修改文档中显示的字段类型，float、double等由原来的number直接变成具体类型。 + 1. 优化注释换行\n\r问题，依赖common-util 1.8.7。 + 2. 修改gitee上bug #I135PG、#I13NR1。 + 3. 添加@requestHeader注解的支持，文档自定将参数绑定到请求头列表中。 + 4. 增加javadoc apiNote tag的支持。 + 5. 解决扫描分析controller中private方法的问题。 + 6. 添加支持@RequestParam注解重写参数名和设置默认值的文档解析。 + 7. 支持使用@PostMapping和@PutMapping请求自定义注解接收单个json参数场景下生成json请求实例。 + 8. 新增对Spring ResponseEntity的解析。 + 9. 增加内部类返回结构解析。 + 10. 修改文档中显示的字段类型，float、double等由原来的number直接变成具体类型。 + #### 版本号：1.7.1 + - 更新日期：已废弃 - 更新内容： - 1. 优化注释换行\n\r问题。 - 2. 修改bug #I135PG - 3. 添加requestHeader功能 + 1. 优化注释换行\n\r问题。 + 2. 修改bug #I135PG + 3. 添加requestHeader功能 + #### 版本号：1.7.0 + - 更新日期：2019-09-30 - 更新内容： - 1. 优化代码。 - 2. 添加生成HTML5和Asciidoctor文档的功能。 - 3. 增加开放API数据接口功能。 - 4. 支持Callable,Future,CompletableFuture等异步接口返回的推导。 - 5. 支持Spring Boot Web Flux(Controller方式书写)。 + 1. 优化代码。 + 2. 添加生成HTML5和Asciidoctor文档的功能。 + 3. 增加开放API数据接口功能。 + 4. 支持Callable,Future,CompletableFuture等异步接口返回的推导。 + 5. 支持Spring Boot Web Flux(Controller方式书写)。 + #### 版本号：1.6.4 + - 更新日期：2019-09-23 - 更新内容： - 1. 优化代码 - 2. 增加对普通的get请求参数拼装示例的生成 - 3. 增加spring mvc占位符restful url请求示例生成 + 1. 优化代码 + 2. 增加对普通的get请求参数拼装示例的生成 + 3. 增加spring mvc占位符restful url请求示例生成 + #### 版本号：1.6.2 + - 更新日期：2019-09-13 - 更新内容： - 1. 修改字段注释多行显示错误bug - 2. 字段描述文档增加@Since tag的支持 - 3. 解析代码忽略WebRequest类防止生产过多信息 - 4. 升级基础库依赖版本 + 1. 修改字段注释多行显示错误bug + 2. 字段描述文档增加@Since tag的支持 + 3. 解析代码忽略WebRequest类防止生产过多信息 + 4. 升级基础库依赖版本 + #### 版本号：1.3 + - 更新日期：2018-09-15 - 更新内容： - 1. 增加PutMapping和DeleteMapping支持 - 2. 添加字符串date和Date类型时间的模拟值生成 + 1. 增加PutMapping和DeleteMapping支持 + 2. 添加字符串date和Date类型时间的模拟值生成 + #### 版本号：1.2 + - 更新日期：2018-09-04 - 更新内容： - 1. 根据用户反馈增加controller报名过滤功能，该功能为可选项 + 1. 根据用户反馈增加controller报名过滤功能，该功能为可选项 + #### 版本号：1.1 + - 更新日期：2018-08-30 - 更新内容： - 1. 修改PostMapping和GetMapping value为空报错的bug - 2. 增强时间字段的mock数据创建 - 3. 修改smart-doc解析自引用对象出错的bug + 1. 修改PostMapping和GetMapping value为空报错的bug + 2. 增强时间字段的mock数据创建 + 3. 修改smart-doc解析自引用对象出错的bug + #### 版本号：1.0 + - 更新日期：2018-08-25 - 更新内容： - 1. smart-doc增加将所有文档导出归档到一个markdown中件的功能 - 2. 参考阿里开发手册将直接提升到1.0，之前的版本主要是个人内部测试 + 1. smart-doc增加将所有文档导出归档到一个markdown中件的功能 + 2. 参考阿里开发手册将直接提升到1.0，之前的版本主要是个人内部测试 #### 版本号：0.5 + - 更新日期：2018-08-23 - 更新内容： - 1. 将api-doc重命名为smart-doc并发布到中央仓库 + 1. 将api-doc重命名为smart-doc并发布到中央仓库 + #### 版本号：0.4 + - 更新日期：2018-07-11 - 更新内容： - 1. 修改api-doc对类继承属性的支持。 + 1. 修改api-doc对类继承属性的支持。 #### 版本号：0.3 + - 更新日期：2018-07-10 - 更新内容： - 1. api-doc增加对jackson和fastjson注解的支持，可根据注解定义来生成返回信息。 + 1. api-doc增加对jackson和fastjson注解的支持，可根据注解定义来生成返回信息。 + ### 版本号：0.2 + - 更新日期：2018-07-07 - 更新内容： - 1. 修改api-doc泛型推导的bug. + 1. 修改api-doc泛型推导的bug. ### 版本号：0.1 + - 更新日期：2018-06-25 - 更新内容： - 1. 手册将api-doc发布到中央仓库 \ No newline at end of file + 1. 手册将api-doc发布到中央仓库 \ No newline at end of file diff --git a/README.md b/README.md index 23c54b1..51f0623 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,14 @@ [![chinese](https://img.shields.io/badge/chinese-中文文档-brightgreen)](https://github.com/shalousun/smart-doc/blob/master/README_CN.md) ## Introduce -smart-doc is a tool that supports both JAVA REST API and Apache Dubbo RPC interface document generation. Smart-doc is based on interface source code analysis to generate interface documents, and zero annotation intrusion. -You only need to write Javadoc comments when developing, smart-doc can help you generate Markdown or HTML5 document. -smart-doc does not need to inject annotations into the code like Swagger. + +smart-doc is a tool that supports both JAVA REST API and Apache Dubbo RPC interface document generation. Smart-doc is +based on interface source code analysis to generate interface documents, and zero annotation intrusion. You only need to +write Javadoc comments when developing, smart-doc can help you generate Markdown or HTML5 document. smart-doc does not +need to inject annotations into the code like Swagger. + ## Features + - Zero annotation, zero learning cost, only need to write standard JAVA document comments. - Automatic derivation based on source code interface definition, powerful return structure derivation support. - Support Spring MVC, Spring Boot, Spring Boot Web Flux (Not support endpoint), Feign. @@ -19,25 +23,38 @@ smart-doc does not need to inject annotations into the code like Swagger. - Support JSR-303 parameter verification specification. - Support for automatic generation of request examples based on request parameters. - Support for generating JSON return value examples. -- Support for loading source code from outside the project to generate field comments (including the sources jar package). +- Support for loading source code from outside the project to generate field comments (including the sources jar + package). - Support for generating multiple formats of documents: Markdown,HTML5,Asciidoctor,Postman Collection 2.0+,OpenAPI 3.0. - Support for exporting error codes and data dictionary codes to API documentation. - The debug html5 page fully supports file upload and download testing. - Support Apache Dubbo RPC. + ## Best Practice -smart-doc + [Torna](http://torna.cn) form an industry-leading document generation and management solution, using smart-doc to complete Java source code analysis and extract annotations to generate API documents without intrusion, and automatically push the documents to the Torna enterprise-level interface document management platform. + +smart-doc + [Torna](http://torna.cn) form an industry-leading document generation and management solution, using +smart-doc to complete Java source code analysis and extract annotations to generate API documents without intrusion, and +automatically push the documents to the Torna enterprise-level interface document management platform. ![smart-doc+torna](https://raw.githubusercontent.com/shalousun/smart-doc/master/images/smart-doc-torna.png) + ## Getting Started + [Smart-doc Samples](https://github.com/shalousun/smart-doc-demo.git)。 + ``` # git clone https://github.com/shalousun/smart-doc-demo.git ``` -This example already provides a static html document generated in advance. You can start the Spring Boot project and then go directly to `http://localhost:8080/doc/api.html` to view the interface documentation generated by smart-doc. -Of course, you can also browse `http://localhost:8080/doc/api.html`, -which looks a html like generated by `asciidoctor-maven-plugin` plugin. + +This example already provides a static html document generated in advance. You can start the Spring Boot project and +then go directly to `http://localhost:8080/doc/api.html` to view the interface documentation generated by smart-doc. Of +course, you can also browse `http://localhost:8080/doc/api.html`, which looks a html like generated +by `asciidoctor-maven-plugin` plugin. + ### Add Maven Plugin + Add [smart-doc-maven-plugin](https://github.com/smart-doc-group/smart-doc-maven-plugin) in your pom.xml. + ``` com.github.shalousun @@ -70,12 +87,15 @@ Add [smart-doc-maven-plugin](https://github.com/smart-doc-group/smart-doc-maven- ``` + ### Configuration -Create a JSON configuration file in your project. The smart-doc-maven-plugin plugin will use this configuration information. -For example, create `/src/main/resources/smart-doc.json` in the project. -The configuration contents are as follows. + +Create a JSON configuration file in your project. The smart-doc-maven-plugin plugin will use this configuration +information. For example, create `/src/main/resources/smart-doc.json` in the project. The configuration contents are as +follows. **Minimize configuration:** + ``` { "allInOne": true, // whether to merge documents into one file, generally recommended as true @@ -83,12 +103,14 @@ The configuration contents are as follows. "outPath": "src/main/resources/static/doc" //Set the api document output path. } ``` -Only the above three simple configuration items can make smart-doc-maven-plugin work. -In fact, only the outPath configuration item is necessary. + +Only the above three simple configuration items can make smart-doc-maven-plugin work. In fact, only the outPath +configuration item is necessary. **Detailed configuration content:** When you need to use smart-doc to generate more API document information, you can add detailed configuration content. + ``` { "serverUrl": "http://127.0.0.1", // Set the server address, not required @@ -182,10 +204,14 @@ When you need to use smart-doc to generate more API document information, you ca }] } ``` -**Note:** This JSON configuration can be converted into JSON using smart-doc's ApiConfig Object. -So the project configuration can also refer to the introduction of smart-doc. + +**Note:** This JSON configuration can be converted into JSON using smart-doc's ApiConfig Object. So the project +configuration can also refer to the introduction of smart-doc. + ### Generated document + #### Run Plugin with MAVEN command + ``` // Generate html mvn -Dfile.encoding=UTF-8 smart-doc:html @@ -208,10 +234,12 @@ mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc // Push dubbo rpc document to Torna mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc ``` -**Note:** Under the window system, if you use the maven command line to perform document generation, -non-English characters may be garbled, so you need to specify `-Dfile.encoding = UTF-8` during execution. + +**Note:** Under the window system, if you use the maven command line to perform document generation, non-English +characters may be garbled, so you need to specify `-Dfile.encoding = UTF-8` during execution. View maven's coding + ``` # mvn -version Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00) @@ -221,49 +249,76 @@ 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 -On Use IntelliJ IDE, if you have added smart-doc-maven-plugin to the project, -you can directly find the plugin smart-doc plugin and click to generate API documentation. + +On Use IntelliJ IDE, if you have added smart-doc-maven-plugin to the project, you can directly find the plugin smart-doc +plugin and click to generate API documentation. ![smart-doc-maven-plugin](https://raw.githubusercontent.com/shalousun/smart-doc-maven-plugin/master/images/idea.png) + ### Use Gradle Plugin + If you use gradle to build the project, you can refer to the documentation of the gradle plugin to integrate, [smart-doc-gradle-plugin](https://github.com/smart-doc-group/smart-doc-gradle-plugin/blob/master/README.md) + ### Generated document example + #### Interface header rendering + ![header](https://images.gitee.com/uploads/images/2019/1231/223538_be45f8a9_144669.png "header.png") + #### Request parameter example rendering + ![request-params](https://images.gitee.com/uploads/images/2019/1231/223710_88933f55_144669.png "request.png") + #### Response parameter example renderings + ![response-fields](https://images.gitee.com/uploads/images/2019/1231/223817_32bea6dc_144669.png "response.png") -## Integration through unit tests -You can generate documentation by adding smart-doc dependencies directly to your project and then writing unit tests to start smart-doc. -we still recommend that you use the smart-doc-maven-plugin plugin. + +## Integration through unit tests + +You can generate documentation by adding smart-doc dependencies directly to your project and then writing unit tests to +start smart-doc. we still recommend that you use the smart-doc-maven-plugin plugin. [Use smart-doc by junit test](https://github.com/smart-doc-group/smart-doc/wiki/Use-smart-doc-by-junit-test) + ## Building + You could build with the following commands. (Java 1.8 is required to build the master branch) + ``` mvn clean install -Dmaven.test.skip=true ``` + ## TODO + - Jakarta RS-API 2.x + ## Other reference + - [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki) ## Who is using -These are only part of the companies using smart-doc, for reference only. If you are using smart-doc, please [add your company here](https://github.com/shalousun/smart-doc/issues/12) to tell us your scenario to make smart-doc better. + +These are only part of the companies using smart-doc, for reference only. If you are using smart-doc, +please [add your company here](https://github.com/shalousun/smart-doc/issues/12) to tell us your scenario to make +smart-doc better. ![IFLYTEK](https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/iflytek.png)       -   + +   - ## License -Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://github.com/shalousun/smart-doc/blob/master/LICENSE) file for details. + +Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://github.com/shalousun/smart-doc/blob/master/LICENSE) +file for details. + ## Contact + Email： 836575280@qq.com diff --git a/README_CN.md b/README_CN.md index d36b0e6..efb81ea 100644 --- a/README_CN.md +++ b/README_CN.md @@ -6,16 +6,18 @@ ![java version](https://img.shields.io/badge/JAVA-1.8+-green.svg) ## Introduce + smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念， -完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释， -smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。 +完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman +Collection2.0+、OpenAPI 3.0+的文档。 $\color{red}{你给我的star，胜过所有读过的诗—smart-doc}$ -> 无论你是很有经验的大佬、还是刚入行的萌新。遇到使用疑惑时，我们希望你能仔细阅读smart-doc官方码云的wiki文档。我们将smart-doc及其插件的 -每一个配置项和可能在日常中遇到的问题都整理到了文档中。仔细阅读文档就是对开源项目最大的支持。 +> 无论你是很有经验的大佬、还是刚入行的萌新。遇到使用疑惑时，我们希望你能仔细阅读smart-doc官方码云的wiki文档。我们将smart-doc及其插件的 每一个配置项和可能在日常中遇到的问题都整理到了文档中。仔细阅读文档就是对开源项目最大的支持。 [wiki文档](https://gitee.com/smart-doc-team/smart-doc/wikis/HOME?sort_id=3127893) + ## Features + - 零注解、零学习成本、只需要写标准JAVA注释。 - 基于源代码接口定义自动推导，强大的返回结构推导。 - 支持Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。 @@ -25,33 +27,40 @@ $\color{red}{你给我的star，胜过所有读过的诗—smart-doc}$ - 对一些常用字段定义能够生成有效的模拟值。 - 支持生成JSON返回值示例。 - 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。 -- 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 -Up- 开放文档数据，可自由实现接入文档管理系统。 +- 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 Up- 开放文档数据，可自由实现接入文档管理系统。 - 支持导出错误码和定义在代码中的各种字典码到接口文档。 - 支持Maven、Gradle插件式轻松集成。 - 支持Apache Dubbo RPC接口文档生成。 - debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。 ## Best Practice + smart-doc + [Torna](http://torna.cn) 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。 ![smart-doc+torna](https://gitee.com/smart-doc-team/smart-doc/raw/master/images/smart-doc-torna.png) [smart-doc+Torna文档自动化](https://gitee.com/smart-doc-team/smart-doc/wikis/smart-doc与torna对接?sort_id=3695028) -> Torna是由smart-doc官方独家推动联合研发的企业级文档管理系统，因此smart-doc官方不会对接其它任何的外部文档管理系统，例如像showdoc、yapi -之类的对接请自定内部处理，也不要再给我们提其他文档系统对接的PR。我们核心是把smart-doc+Torna的这套方案打造好。 +> Torna是由smart-doc官方独家推动联合研发的企业级文档管理系统，因此smart-doc官方不会对接其它任何的外部文档管理系统，例如像showdoc、yapi 之类的对接请自定内部处理，也不要再给我们提其他文档系统对接的PR。我们核心是把smart-doc+Torna的这套方案打造好。 + ## Getting Started + smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/devin-alan/api-doc-test.git)。 + ``` # git clone https://gitee.com/devin-alan/api-doc-test.git ``` + 你可以启动这个Spring Boot的项目，然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。 + ### 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 + ``` com.github.shalousun @@ -86,20 +95,24 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc ``` -#### Configuration -在项目中添加创建一个`smart-doc.json`配置文件，插件读取这个配置来生成项目的文档， -这个配置内容实际上就是以前采用单元测试编写的`ApiConfig`转成json后的结果，因此关于配置项说明可以参考原来单元测试的配置。 - **最小配置单元：** +#### Configuration + +在项目中添加创建一个`smart-doc.json`配置文件，插件读取这个配置来生成项目的文档， 这个配置内容实际上就是以前采用单元测试编写的`ApiConfig`转成json后的结果，因此关于配置项说明可以参考原来单元测试的配置。 + +**最小配置单元：** + ``` { "outPath": "D://md2" //指定文档的输出路径,相对路径时请用./开头，eg:./src/main/resources/static/doc } ``` ->如果你想把html文档也打包到应用中一起访问，则建议你配置路径为：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直接设置环境变量 @@ -201,11 +214,15 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc }] } ``` + 上面的JSON配置实例中只有"outPath"是必填项。 **注意：** 对于老用户完全可以通过`Fastjson`或者是`Gson`库将`ApiConfig`转化成JSON配置。 + #### Use Maven Command + 添加好插件和配置文件后可以直接运行Maven命令生成文档。 + ``` //生成html mvn -Dfile.encoding=UTF-8 smart-doc:html @@ -231,35 +248,55 @@ 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 + ![idea中smart-doc-maven插件使用](https://gitee.com/smart-doc-team/smart-doc-maven-plugin/raw/master/images/idea.png "maven_plugin_tasks.png") ### 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 + +### 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) > 单元测试集成存在很多绝限性:
1. 对于多模块项目源码注释很麻烦，也不符合正常开发团队的开发协作。
2. 不方便与CI工具集成 + ### Generated document example + [点击查看文档生成文档效果图](https://gitee.com/smart-doc-team/smart-doc/wikis/文档效果图?sort_id=1652819) + ## Building + 如果你需要自己构建smart-doc，那可以使用下面命令，构建需要依赖Java 1.8。 + ``` mvn clean install -Dmaven.test.skip=true ``` + ## TODO + - 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 the [LICENSE](https://gitee.com/smart-doc-team/smart-doc/blob/master/LICENSE) file for details. + +smart-doc is under the Apache 2.0 license. See +the [LICENSE](https://gitee.com/smart-doc-team/smart-doc/blob/master/LICENSE) file for details. **注意：** smart-doc源代码文件全部带有版权注释，使用关键代码二次开源请保留原始版权，否则后果自负！ + ## Who is using + > 排名不分先后，更多接入公司，欢迎在[https://gitee.com/smart-doc-team/smart-doc/issues/I1594T](https://gitee.com/smart-doc-team/smart-doc/issues/I1594T)登记（仅供开源用户参考） ![IFLYTEK](https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/iflytek.png) @@ -267,11 +304,16 @@ smart-doc is under the Apache 2.0 license. See the [LICENSE](https://gitee.com    -   + +   + ## Award situation + - 2020 年度 OSC 中国开源项目评选”活动中获得「最积极运营项目」 + ## Contact + 愿意参与构建smart-doc或者是需要交流问题可以加入qq群： diff --git a/doc/List.md b/doc/List.md index af7d825..4303219 100644 --- a/doc/List.md +++ b/doc/List.md @@ -3,6 +3,7 @@ # List结构 api-doc对于List中返回基础数据类型都是支持的 + ``` /** * List @@ -14,10 +15,13 @@ public List testList() { return null; } ``` + api-doc生成的响应数据 + ``` [ "ivvqah","isrz5x"] ``` + # List>结构 ``` @@ -30,7 +34,9 @@ public List> testMap() { return null; } ``` + api-doc生成的响应数据 + ``` [{ "mapKey1": "o9mibj", @@ -47,6 +53,7 @@ public List> testMap() { } ``` + 相应数据省略 # 测试List结构 @@ -63,6 +70,7 @@ public List testMap() { ``` # List>结构 + ``` /** * 测试List>结构 @@ -73,7 +81,9 @@ public List> testMap() { return null; } ``` + # List>>超复杂结构 + ``` /** * 测试List>>超复杂结构 @@ -84,7 +94,9 @@ public List>> testMap() { return null; } ``` + api-doc自动返回的数据 + ``` [{ "mapKey": { @@ -102,6 +114,7 @@ api-doc自动返回的数据 } }] ``` + # List,List,List>>超复杂结构 ``` @@ -114,7 +127,9 @@ public List,List,List>> testListString(){ return null; } ``` + # 其他复杂结构 + ``` /** * List,List,List>> @@ -132,5 +147,4 @@ public List,Teacher,Teacher testMap() { return null; } ``` + api-doc 生成的json: + ``` { "mapKey1": 721, "mapKey2": 280 } ``` + # map使用Object 因为api-doc使用的是无侵入静态分析生成api文档，因此对于直接使用Object做map value的接口，api-doc无法准确的生成json。 所以api-doc返回是会在默认json中加一段警告，使用者需要自己去修改返回数据，或者是使用显示的类型数据结构。 + ``` /** * 测试map使用基础数据类型 @@ -36,7 +39,9 @@ public Map testMap() { return null; } ``` + api-doc 生成的json: + ``` { "mapKey": { @@ -44,8 +49,11 @@ api-doc 生成的json: } } ``` + # map中属于自己定义的简单数据结构 + User对象的属性仅仅是基本数据类型 + ``` /** * 测试map使用自定义数据结构 @@ -56,7 +64,9 @@ public Map testMap() { return null; } ``` + api-doc 生成的json: + ``` { "mapKey": { @@ -66,8 +76,11 @@ api-doc 生成的json: } } ``` + # map中属于自己定义的复杂数据结构 + Student对象的属性有基本类型又有User类型和Map类型的属性。 + ``` /** * 测试map使用自定义数据结构 @@ -78,7 +91,9 @@ public Map testMap() { return null; } ``` + api-doc 生成的json: + ``` { "mapKey": { @@ -125,6 +140,7 @@ api-doc 生成的json: } } ``` + # Map,N>超复杂结构 ``` @@ -137,9 +153,11 @@ public Map,User>> testMap() { return null; } ``` + # Map其他复杂结构 对于map的key采用多泛型的情况，目前api-doc也是支持的。 + ``` /** * Map,N>超复杂结构 @@ -149,5 +167,5 @@ public Map,Map,Map>> t return null; } ``` -**注意：** api-doc为了传入的复杂泛型结构数据，做了许多情况的测试，目前基本能兼容系统开发中95%以上的Map返回接口， -也提供了一些能够处理的很复杂的泛型结构，但是这种复杂的泛型结构在开发中是不被推荐的。 \ No newline at end of file + +**注意：** api-doc为了传入的复杂泛型结构数据，做了许多情况的测试，目前基本能兼容系统开发中95%以上的Map返回接口， 也提供了一些能够处理的很复杂的泛型结构，但是这种复杂的泛型结构在开发中是不被推荐的。 \ No newline at end of file diff --git a/doc/error.md b/doc/error.md index 9ca3c5b..c964f1c 100644 --- a/doc/error.md +++ b/doc/error.md @@ -1,5 +1,4 @@ -api-doc对Spring mvc或者SpringBoot应用的Controller接口返回做了一些强制规约，一旦在代码中使用 -这些被api-doc不推荐的接口返回类型，api-doc将会直接报错。 +api-doc对Spring mvc或者SpringBoot应用的Controller接口返回做了一些强制规约，一旦在代码中使用 这些被api-doc不推荐的接口返回类型，api-doc将会直接报错。 # 违反规约的实例 @@ -15,6 +14,7 @@ public Object getMe(){ return null; } ``` + 报错提示：Please do not return java.lang.Object directly in api interface. ## 将非String对象作为Map的key，然后将map作为接口中返回 diff --git a/doc/temp.md b/doc/temp.md index 32c4575..0101046 100644 --- a/doc/temp.md +++ b/doc/temp.md @@ -1,132 +1,130 @@ - - ```java /** - * Get fields - * - * @param cls1 The JavaClass object - * @param counter Recursive counter - * @param addedFields added fields,Field deduplication - * @return list of JavaField - */ - public static List getFields(JavaClass cls1, int counter, HashMap addedFields) { - List fieldList = new ArrayList<>(); - if (null == cls1) { - return fieldList; - } else if ("Object".equals(cls1.getSimpleName()) || "Timestamp".equals(cls1.getSimpleName()) || - "Date".equals(cls1.getSimpleName()) || "Locale".equals(cls1.getSimpleName()) - || "ClassLoader".equals(cls1.getSimpleName()) || JavaClassValidateUtil.isMap(cls1.getFullyQualifiedName()) - || cls1.isEnum() || "Serializable".equals(cls1.getSimpleName())) { - return fieldList; - } else { - String className = cls1.getFullyQualifiedName(); - if (cls1.isInterface() && - !JavaClassValidateUtil.isCollection(className) && - !JavaClassValidateUtil.isMap(className)) { - List methods = cls1.getMethods(); - for (JavaMethod javaMethod : methods) { - String methodName = javaMethod.getName(); - int paramSize = javaMethod.getParameters().size(); - boolean enable = false; - if (methodName.startsWith("get") && !"get".equals(methodName) && paramSize == 0) { - methodName = StringUtil.firstToLowerCase(methodName.substring(3)); - enable = true; - } else if (methodName.startsWith("is") && !"is".equals(methodName) && paramSize == 0) { - methodName = StringUtil.firstToLowerCase(methodName.substring(2)); - enable = true; - } - if (!enable || addedFields.containsKey(methodName)) { - continue; - } - String comment = javaMethod.getComment(); - JavaField javaField = new DefaultJavaField(javaMethod.getReturns(), methodName); - DocJavaField docJavaField = DocJavaField.builder() - .setJavaField(javaField) - .setComment(comment) - .setDocletTags(javaMethod.getTags()) - .setAnnotations(javaMethod.getAnnotations()) - .setFullyQualifiedName(javaField.getType().getFullyQualifiedName()) - .setGenericCanonicalName(javaField.getType().getGenericCanonicalName()); - addedFields.put(methodName, docJavaField); - } - } - // ignore enum parent class - if (!cls1.isEnum()) { - JavaClass parentClass = cls1.getSuperJavaClass(); - getFields(parentClass, counter, addedFields); - List implClasses = cls1.getImplements(); - for (JavaType type : implClasses) { - JavaClass javaClass = (JavaClass) type; - getFields(javaClass, counter, addedFields); - } - } - Map actualJavaTypes = getActualTypesMap(cls1); - List javaMethods = cls1.getMethods(); - for (JavaMethod method : javaMethods) { - String methodName = method.getName(); - int paramSize = method.getParameters().size(); - if (methodName.startsWith("get") && !"get".equals(methodName) && paramSize == 0) { - methodName = StringUtil.firstToLowerCase(methodName.substring(3)); - } else if (methodName.startsWith("is") && !"is".equals(methodName) && paramSize == 0) { - methodName = StringUtil.firstToLowerCase(methodName.substring(2)); - } - if (addedFields.containsKey(methodName)) { - String comment = method.getComment(); - DocJavaField docJavaField = addedFields.get(methodName); - docJavaField.setAnnotations(method.getAnnotations()); - docJavaField.setComment(comment); - addedFields.put(methodName, docJavaField); - } - } - for (JavaField javaField : cls1.getFields()) { - String fieldName = javaField.getName(); - DocJavaField docJavaField = DocJavaField.builder(); - boolean typeChecked = false; - String gicName = javaField.getType().getGenericCanonicalName(); - String subTypeName = javaField.getType().getFullyQualifiedName(); - String actualType = null; - if (JavaClassValidateUtil.isCollection(subTypeName) && - !JavaClassValidateUtil.isCollection(gicName)) { - String[] gNameArr = DocClassUtil.getSimpleGicName(gicName); - actualType = JavaClassUtil.getClassSimpleName(gNameArr[0]); - docJavaField.setArray(true); - typeChecked = true; - } - if (JavaClassValidateUtil.isPrimitive(subTypeName) && !typeChecked) { - docJavaField.setPrimitive(true); - typeChecked = true; - } - if (JavaClassValidateUtil.isFile(subTypeName) && !typeChecked) { - docJavaField.setFile(true); - typeChecked = true; - } - if (javaField.getType().isEnum() && !typeChecked) { - docJavaField.setEnum(true); - } - for (Map.Entry entry : actualJavaTypes.entrySet()) { - String key = entry.getKey(); - JavaType value = entry.getValue(); - if (gicName.contains(key)) { - subTypeName = subTypeName.replaceAll(key, value.getFullyQualifiedName()); - gicName = gicName.replaceAll(key, value.getGenericCanonicalName()); - actualType = value.getFullyQualifiedName(); - } - } - docJavaField.setComment(javaField.getComment()) - .setJavaField(javaField).setFullyQualifiedName(subTypeName) - .setGenericCanonicalName(gicName).setActualJavaType(actualType) - .setAnnotations(javaField.getAnnotations()); - if (addedFields.containsKey(fieldName)) { - addedFields.put(fieldName, docJavaField); - continue; - } - addedFields.put(fieldName, docJavaField); - } - List parentFieldList = addedFields.values().stream() - .filter(v -> Objects.nonNull(v)).collect(Collectors.toList()); - fieldList.addAll(parentFieldList); - } - return fieldList; - } + * Get fields + * + * @param cls1 The JavaClass object + * @param counter Recursive counter + * @param addedFields added fields,Field deduplication + * @return list of JavaField + */ +public static List getFields(JavaClass cls1,int counter,HashMap addedFields){ + List fieldList=new ArrayList<>(); + if(null==cls1){ + return fieldList; + }else if("Object".equals(cls1.getSimpleName())||"Timestamp".equals(cls1.getSimpleName())|| + "Date".equals(cls1.getSimpleName())||"Locale".equals(cls1.getSimpleName()) + ||"ClassLoader".equals(cls1.getSimpleName())||JavaClassValidateUtil.isMap(cls1.getFullyQualifiedName()) + ||cls1.isEnum()||"Serializable".equals(cls1.getSimpleName())){ + return fieldList; + }else{ + String className=cls1.getFullyQualifiedName(); + if(cls1.isInterface()&& + !JavaClassValidateUtil.isCollection(className)&& + !JavaClassValidateUtil.isMap(className)){ + List methods=cls1.getMethods(); + for(JavaMethod javaMethod:methods){ + String methodName=javaMethod.getName(); + int paramSize=javaMethod.getParameters().size(); + boolean enable=false; + if(methodName.startsWith("get")&&!"get".equals(methodName)&¶mSize==0){ + methodName=StringUtil.firstToLowerCase(methodName.substring(3)); + enable=true; + }else if(methodName.startsWith("is")&&!"is".equals(methodName)&¶mSize==0){ + methodName=StringUtil.firstToLowerCase(methodName.substring(2)); + enable=true; + } + if(!enable||addedFields.containsKey(methodName)){ + continue; + } + String comment=javaMethod.getComment(); + JavaField javaField=new DefaultJavaField(javaMethod.getReturns(),methodName); + DocJavaField docJavaField=DocJavaField.builder() + .setJavaField(javaField) + .setComment(comment) + .setDocletTags(javaMethod.getTags()) + .setAnnotations(javaMethod.getAnnotations()) + .setFullyQualifiedName(javaField.getType().getFullyQualifiedName()) + .setGenericCanonicalName(javaField.getType().getGenericCanonicalName()); + addedFields.put(methodName,docJavaField); + } + } + // ignore enum parent class + if(!cls1.isEnum()){ + JavaClass parentClass=cls1.getSuperJavaClass(); + getFields(parentClass,counter,addedFields); + List implClasses=cls1.getImplements(); + for(JavaType type:implClasses){ + JavaClass javaClass=(JavaClass)type; + getFields(javaClass,counter,addedFields); + } + } + Map actualJavaTypes=getActualTypesMap(cls1); + List javaMethods=cls1.getMethods(); + for(JavaMethod method:javaMethods){ + String methodName=method.getName(); + int paramSize=method.getParameters().size(); + if(methodName.startsWith("get")&&!"get".equals(methodName)&¶mSize==0){ + methodName=StringUtil.firstToLowerCase(methodName.substring(3)); + }else if(methodName.startsWith("is")&&!"is".equals(methodName)&¶mSize==0){ + methodName=StringUtil.firstToLowerCase(methodName.substring(2)); + } + if(addedFields.containsKey(methodName)){ + String comment=method.getComment(); + DocJavaField docJavaField=addedFields.get(methodName); + docJavaField.setAnnotations(method.getAnnotations()); + docJavaField.setComment(comment); + addedFields.put(methodName,docJavaField); + } + } + for(JavaField javaField:cls1.getFields()){ + String fieldName=javaField.getName(); + DocJavaField docJavaField=DocJavaField.builder(); + boolean typeChecked=false; + String gicName=javaField.getType().getGenericCanonicalName(); + String subTypeName=javaField.getType().getFullyQualifiedName(); + String actualType=null; + if(JavaClassValidateUtil.isCollection(subTypeName)&& + !JavaClassValidateUtil.isCollection(gicName)){ + String[]gNameArr=DocClassUtil.getSimpleGicName(gicName); + actualType=JavaClassUtil.getClassSimpleName(gNameArr[0]); + docJavaField.setArray(true); + typeChecked=true; + } + if(JavaClassValidateUtil.isPrimitive(subTypeName)&&!typeChecked){ + docJavaField.setPrimitive(true); + typeChecked=true; + } + if(JavaClassValidateUtil.isFile(subTypeName)&&!typeChecked){ + docJavaField.setFile(true); + typeChecked=true; + } + if(javaField.getType().isEnum()&&!typeChecked){ + docJavaField.setEnum(true); + } + for(Map.Entry entry:actualJavaTypes.entrySet()){ + String key=entry.getKey(); + JavaType value=entry.getValue(); + if(gicName.contains(key)){ + subTypeName=subTypeName.replaceAll(key,value.getFullyQualifiedName()); + gicName=gicName.replaceAll(key,value.getGenericCanonicalName()); + actualType=value.getFullyQualifiedName(); + } + } + docJavaField.setComment(javaField.getComment()) + .setJavaField(javaField).setFullyQualifiedName(subTypeName) + .setGenericCanonicalName(gicName).setActualJavaType(actualType) + .setAnnotations(javaField.getAnnotations()); + if(addedFields.containsKey(fieldName)){ + addedFields.put(fieldName,docJavaField); + continue; + } + addedFields.put(fieldName,docJavaField); + } + List parentFieldList=addedFields.values().stream() + .filter(v->Objects.nonNull(v)).collect(Collectors.toList()); + fieldList.addAll(parentFieldList); + } + return fieldList; + } ``` \ No newline at end of file diff --git a/pom.xml b/pom.xml index db6e2a8..6209ddd 100644 --- a/pom.xml +++ b/pom.xml @@ -9,7 +9,9 @@ smart-doc https://github.com/smart-doc-group/smart-doc.git - Smart-doc is a tool that supports both JAVA RESTFUL API and Apache Dubbo RPC interface document generation. + Smart-doc is a tool that supports both JAVA RESTFUL API and Apache Dubbo RPC interface document + generation. + diff --git a/src/main/java/com/power/doc/builder/ApiDataBuilder.java b/src/main/java/com/power/doc/builder/ApiDataBuilder.java index bb117fc..b679e0f 100644 --- a/src/main/java/com/power/doc/builder/ApiDataBuilder.java +++ b/src/main/java/com/power/doc/builder/ApiDataBuilder.java @@ -39,7 +39,7 @@ public class ApiDataBuilder { * @return List of ApiDoc */ public static ApiAllData getApiData(ApiConfig config) { - return getApiData(config,false); + return getApiData(config, false); } /** @@ -49,10 +49,10 @@ public class ApiDataBuilder { * @return List of ApiDoc */ public static ApiAllData getApiDataTree(ApiConfig config) { - return getApiData(config,true); + return getApiData(config, true); } - private static ApiAllData getApiData(ApiConfig config,boolean toTree) { + private static ApiAllData getApiData(ApiConfig config, boolean toTree) { config.setParamsDataToTree(toTree); DocBuilderTemplate builderTemplate = new DocBuilderTemplate(); builderTemplate.checkAndInitForGetApiData(config); diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index 6603e7b..d2bcaa9 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -42,14 +42,10 @@ import static com.power.doc.constants.DocGlobalConstants.*; */ public class HtmlApiDocBuilder { - private static long now = System.currentTimeMillis(); - - private static String INDEX_HTML = "index.html"; - private static final String ERROR_CODE_HTML = "error.html"; - private static final String DICT_HTML = "dict.html"; - + private static long now = System.currentTimeMillis(); + private static String INDEX_HTML = "index.html"; /** * build controller api diff --git a/src/main/java/com/power/doc/builder/ProjectDocConfigBuilder.java b/src/main/java/com/power/doc/builder/ProjectDocConfigBuilder.java index 845c1f5..659d085 100644 --- a/src/main/java/com/power/doc/builder/ProjectDocConfigBuilder.java +++ b/src/main/java/com/power/doc/builder/ProjectDocConfigBuilder.java @@ -52,7 +52,7 @@ public class ProjectDocConfigBuilder { private Map customRespFieldMap = new ConcurrentHashMap<>(); - private Map customReqFieldMap = new ConcurrentHashMap<>(); + private Map customReqFieldMap = new ConcurrentHashMap<>(); private Map replaceClassMap = new ConcurrentHashMap<>(); @@ -192,6 +192,7 @@ public class ProjectDocConfigBuilder { } } } + /** * 设置高亮样式 */ diff --git a/src/main/java/com/power/doc/builder/TornaBuilder.java b/src/main/java/com/power/doc/builder/TornaBuilder.java index 0043803..486f76f 100644 --- a/src/main/java/com/power/doc/builder/TornaBuilder.java +++ b/src/main/java/com/power/doc/builder/TornaBuilder.java @@ -89,7 +89,7 @@ public class TornaBuilder { for (ApiDoc a : apiDocs) { api = new Apis(); api.setName(StringUtils.isBlank(a.getDesc()) ? a.getName() : a.getDesc()); - api.setItems(buildApis(a.getList(), TornaUtil.setDebugEnv(apiConfig,tornaApi))); + api.setItems(buildApis(a.getList(), TornaUtil.setDebugEnv(apiConfig, tornaApi))); api.setIsFolder(TornaConstants.YES); api.setAuthor(a.getAuthor()); apisList.add(api); @@ -100,7 +100,7 @@ public class TornaBuilder { //获取返回结果 String responseMsg = OkHttp3Util.syncPostJson(apiConfig.getOpenUrl(), new Gson().toJson(requestJson)); //开启调试时打印请求信息 - TornaUtil.printDebugInfo(apiConfig,responseMsg,requestJson); + TornaUtil.printDebugInfo(apiConfig, responseMsg, requestJson); } } diff --git a/src/main/java/com/power/doc/builder/rpc/RpcDocBuilderTemplate.java b/src/main/java/com/power/doc/builder/rpc/RpcDocBuilderTemplate.java index abef0e9..cfc7350 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcDocBuilderTemplate.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcDocBuilderTemplate.java @@ -52,10 +52,8 @@ import static com.power.doc.constants.DocGlobalConstants.RPC_OUT_DIR; */ public class RpcDocBuilderTemplate extends BaseDocBuilderTemplate { - private static long now = System.currentTimeMillis(); - private static final String DEPENDENCY_TITLE = "Add dependency"; - + private static long now = System.currentTimeMillis(); public void checkAndInit(ApiConfig config) { super.checkAndInit(config); diff --git a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java index dd5c753..65fcd40 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java @@ -52,7 +52,7 @@ public class RpcMarkdownBuilder { } /** - *Only for smart-doc maven plugin and gradle plugin. + * Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder diff --git a/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java index 20127ab..308102d 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java @@ -75,6 +75,7 @@ public class RpcTornaBuilder { List apiDocList = docBuildTemplate.getApiData(configBuilder); buildTorna(apiDocList, config); } + public static void buildTorna(List apiDocs, ApiConfig apiConfig) { TornaApi tornaApi = new TornaApi(); tornaApi.setAuthor(StringUtil.isEmpty(apiConfig.getAuthor()) ? System.getProperty("user.name") : apiConfig.getAuthor()); @@ -84,12 +85,12 @@ public class RpcTornaBuilder { for (RpcApiDoc a : apiDocs) { api = new Apis(); api.setName(StringUtils.isBlank(a.getDesc()) ? a.getName() : a.getDesc()); - TornaUtil.setDebugEnv(apiConfig,tornaApi); + TornaUtil.setDebugEnv(apiConfig, tornaApi); api.setItems(buildDubboApis(a.getList())); api.setIsFolder(TornaConstants.YES); api.setAuthor(a.getAuthor()); api.setDubboInfo(new DubboInfo().builder() - .setAuthor(a.getAuthor()) + .setAuthor(a.getAuthor()) .setProtocol(a.getProtocol()) .setVersion(a.getVersion()) .setDependency(TornaUtil.buildDependencies(apiConfig.getRpcApiDependencies())) @@ -102,6 +103,6 @@ public class RpcTornaBuilder { //获取返回结果 String responseMsg = OkHttp3Util.syncPostJson(apiConfig.getOpenUrl(), new Gson().toJson(requestJson)); //开启调试时打印请求信息 - TornaUtil.printDebugInfo(apiConfig,responseMsg,requestJson); + TornaUtil.printDebugInfo(apiConfig, responseMsg, requestJson); } } diff --git a/src/main/java/com/power/doc/constants/DocTags.java b/src/main/java/com/power/doc/constants/DocTags.java index 18c2a8f..f6f88f5 100644 --- a/src/main/java/com/power/doc/constants/DocTags.java +++ b/src/main/java/com/power/doc/constants/DocTags.java @@ -60,7 +60,7 @@ public interface DocTags { /** * java deprecated tag */ - String DEPRECATED= "deprecated"; + String DEPRECATED = "deprecated"; /** * custom ignore tag diff --git a/src/main/java/com/power/doc/constants/DocValidatorAnnotationEnum.java b/src/main/java/com/power/doc/constants/DocValidatorAnnotationEnum.java index 07c9360..3dfd00f 100644 --- a/src/main/java/com/power/doc/constants/DocValidatorAnnotationEnum.java +++ b/src/main/java/com/power/doc/constants/DocValidatorAnnotationEnum.java @@ -69,8 +69,7 @@ public enum DocValidatorAnnotationEnum { RANGE("Range"), - VALIDATED("Validated") - ; + VALIDATED("Validated"); private String value; diff --git a/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java b/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java index ee59773..4a9082d 100644 --- a/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java +++ b/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java @@ -24,6 +24,7 @@ package com.power.doc.constants; /** * dubbo annotation + * * @author yu 2020/1/29. */ public interface DubboAnnotationConstants { @@ -38,5 +39,5 @@ public interface DubboAnnotationConstants { /** * support ali dubbo */ - String ALI_DUBBO_SERVICE= "com.alibaba.dubbo.config.annotation.Service"; + String ALI_DUBBO_SERVICE = "com.alibaba.dubbo.config.annotation.Service"; } diff --git a/src/main/java/com/power/doc/constants/SpringMvcRequestAnnotationsEnum.java b/src/main/java/com/power/doc/constants/SpringMvcRequestAnnotationsEnum.java index c60c16a..0b226bf 100644 --- a/src/main/java/com/power/doc/constants/SpringMvcRequestAnnotationsEnum.java +++ b/src/main/java/com/power/doc/constants/SpringMvcRequestAnnotationsEnum.java @@ -37,7 +37,8 @@ public enum SpringMvcRequestAnnotationsEnum { REQUEST_BODY("RequestBody"), REQUEST_BODY_FULLY("org.springframework.web.bind.annotation.RequestBody"), REQUEST_HERDER("RequestHeader"), - REQUEST_HERDER_FULLY("org.springframework.web.bind.annotation.RequestHeader"),; + REQUEST_HERDER_FULLY("org.springframework.web.bind.annotation.RequestHeader"), + ; private String value; SpringMvcRequestAnnotationsEnum(String value) { diff --git a/src/main/java/com/power/doc/filter/DefaultReturnFilter.java b/src/main/java/com/power/doc/filter/DefaultReturnFilter.java index 2237880..4906b56 100644 --- a/src/main/java/com/power/doc/filter/DefaultReturnFilter.java +++ b/src/main/java/com/power/doc/filter/DefaultReturnFilter.java @@ -26,6 +26,7 @@ import com.power.doc.model.ApiReturn; /** * must be put last + * * @author yu 2020/4/17. */ public class DefaultReturnFilter implements ReturnTypeFilter { diff --git a/src/main/java/com/power/doc/filter/ReturnTypeFilter.java b/src/main/java/com/power/doc/filter/ReturnTypeFilter.java index 2455dd7..eefdebc 100644 --- a/src/main/java/com/power/doc/filter/ReturnTypeFilter.java +++ b/src/main/java/com/power/doc/filter/ReturnTypeFilter.java @@ -26,12 +26,14 @@ import com.power.doc.model.ApiReturn; /** * Chain Of Responsibility Pattern + * * @author yu 2020/4/17. */ public interface ReturnTypeFilter { /** * filter return Type + * * @param fullyName full type name * @return ApiReturn */ diff --git a/src/main/java/com/power/doc/helper/FormDataBuildHelper.java b/src/main/java/com/power/doc/helper/FormDataBuildHelper.java index 519e1c0..251cb07 100644 --- a/src/main/java/com/power/doc/helper/FormDataBuildHelper.java +++ b/src/main/java/com/power/doc/helper/FormDataBuildHelper.java @@ -28,6 +28,7 @@ import com.power.doc.builder.ProjectDocConfigBuilder; import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.DocTags; import com.power.doc.model.ApiConfig; +import com.power.doc.model.CustomField; import com.power.doc.model.DocJavaField; import com.power.doc.model.FormData; import com.power.doc.utils.DocClassUtil; @@ -137,6 +138,12 @@ public class FormDataBuildHelper { } else { fieldValue = DocUtil.getValByTypeAndFieldName(typeSimpleName, field.getName()); } + CustomField customRequestField = builder.getCustomReqFieldMap().get(fieldName); + // cover request value + if (Objects.nonNull(customRequestField) && Objects.nonNull(customRequestField.getValue()) + && JavaClassUtil.isTargetChildClass(simpleName, customRequestField.getOwnerClassName())) { + fieldValue = String.valueOf(customRequestField.getValue()); + } FormData formData = new FormData(); formData.setKey(pre + fieldName); formData.setType("text"); diff --git a/src/main/java/com/power/doc/helper/JsonBuildHelper.java b/src/main/java/com/power/doc/helper/JsonBuildHelper.java index 5c25c89..349fc55 100644 --- a/src/main/java/com/power/doc/helper/JsonBuildHelper.java +++ b/src/main/java/com/power/doc/helper/JsonBuildHelper.java @@ -183,7 +183,7 @@ public class JsonBuildHelper { } else if (DocGlobalConstants.JAVA_OBJECT_FULLY.equals(typeName)) { data.append("{\"object\":\" any object\"},"); // throw new RuntimeException("Please do not return java.lang.Object directly in api interface."); - } else if(JavaClassValidateUtil.isReactor(typeName)) { + } else if (JavaClassValidateUtil.isReactor(typeName)) { data.append(buildJson(globGicName[0], typeName, isResp, nextLevel, registryClasses, builder)); return data.toString(); } else { @@ -234,10 +234,10 @@ public class JsonBuildHelper { String fieldGicName = docField.getGenericCanonicalName(); CustomField customResponseField = builder.getCustomRespFieldMap().get(fieldName); CustomField customRequestField = builder.getCustomReqFieldMap().get(fieldName); - if(customRequestField !=null && typeName.equals(customRequestField.getOwnerClassName()) && (customRequestField.isIgnore()) && !isResp){ + if (customRequestField != null && typeName.equals(customRequestField.getOwnerClassName()) && (customRequestField.isIgnore()) && !isResp) { continue; } - if(customResponseField !=null && typeName.equals(customResponseField.getOwnerClassName()) && (customResponseField.isIgnore()) && isResp){ + if (customResponseField != null && typeName.equals(customResponseField.getOwnerClassName()) && (customResponseField.isIgnore()) && isResp) { continue; } data0.append("\"").append(fieldName).append("\":"); @@ -252,19 +252,19 @@ public class JsonBuildHelper { } } if (JavaClassValidateUtil.isPrimitive(subTypeName)) { - int data0Length = data0.length(); + int data0Length = data0.length(); if (StringUtil.isEmpty(fieldValue)) { fieldValue = DocUtil.getValByTypeAndFieldName(typeSimpleName, field.getName()); } if (null != customRequestField && !isResp && customRequestField.getOwnerClassName().equals(typeName)) { JavaFieldUtil.buildCustomField(data0, typeSimpleName, customRequestField); } - if (null != customResponseField && isResp && customResponseField.getOwnerClassName().equals(typeName)) { + if (null != customResponseField && isResp && customResponseField.getOwnerClassName().equals(typeName)) { JavaFieldUtil.buildCustomField(data0, typeSimpleName, customResponseField); } - if(data0.length()==data0Length) { - data0.append(fieldValue).append(","); - } + if (data0.length() == data0Length) { + data0.append(fieldValue).append(","); + } } else { if (JavaClassValidateUtil.isCollection(subTypeName) || JavaClassValidateUtil.isArray(subTypeName)) { if (StringUtil.isNotEmpty(fieldValue)) { @@ -395,6 +395,4 @@ public class JsonBuildHelper { } - - } diff --git a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java index 889049e..391334f 100644 --- a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java +++ b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java @@ -51,8 +51,7 @@ import static com.power.doc.constants.DocGlobalConstants.*; */ public class ParamsBuildHelper { - public static List buildParams(String className, String pre, int level, String isRequired, - Map responseFieldMap, boolean isResp, + public static List buildParams(String className, String pre, int level, String isRequired, boolean isResp, Map registryClasses, ProjectDocConfigBuilder projectBuilder, List groupClasses, int pid, boolean jsonRequest) { String maxLength = null; @@ -72,6 +71,7 @@ public class ParamsBuildHelper { if (registryClasses.containsKey(className) && level > registryClasses.size()) { return paramList; } + Map responseFieldMap = projectBuilder.getCustomRespFieldMap(); boolean skipTransientField = apiConfig.isSkipTransientField(); boolean isShowJavaType = projectBuilder.getApiConfig().getShowJavaType(); boolean requestFieldToUnderline = projectBuilder.getApiConfig().isRequestFieldToUnderline(); @@ -94,12 +94,12 @@ public class ParamsBuildHelper { if (JavaClassValidateUtil.isArray(gicName)) { gicName = gicName.substring(0, gicName.indexOf("[")); } - paramList.addAll(buildParams(gicName, pre, nextLevel, isRequired, responseFieldMap, isResp, + paramList.addAll(buildParams(gicName, pre, nextLevel, isRequired, isResp, registryClasses, projectBuilder, groupClasses, pid, jsonRequest)); } } else if (JavaClassValidateUtil.isMap(simpleName)) { if (globGicName.length == 2) { - paramList.addAll(buildParams(globGicName[1], pre, nextLevel, isRequired, responseFieldMap, isResp, + paramList.addAll(buildParams(globGicName[1], pre, nextLevel, isRequired, isResp, registryClasses, projectBuilder, groupClasses, pid, jsonRequest)); } } else if (DocGlobalConstants.JAVA_OBJECT_FULLY.equals(className)) { @@ -111,7 +111,7 @@ public class ParamsBuildHelper { } paramList.add(param); } else if (JavaClassValidateUtil.isReactor(simpleName)) { - paramList.addAll(buildParams(globGicName[0], pre, nextLevel, isRequired, responseFieldMap, isResp, + paramList.addAll(buildParams(globGicName[0], pre, nextLevel, isRequired, isResp, registryClasses, projectBuilder, groupClasses, pid, jsonRequest)); } else { out: @@ -151,11 +151,13 @@ public class ParamsBuildHelper { boolean strRequired = false; int annotationCounter = 0; CustomField customResponseField = responseFieldMap.get(fieldName); - if (customResponseField != null && JavaClassUtil.isTargetChildClass(simpleName, customResponseField.getOwnerClassName()) && (customResponseField.isIgnore()) && isResp) { + if (customResponseField != null && JavaClassUtil.isTargetChildClass(simpleName, customResponseField.getOwnerClassName()) + && (customResponseField.isIgnore()) && isResp) { continue; } CustomField customRequestField = projectBuilder.getCustomReqFieldMap().get(fieldName); - if (customRequestField != null && JavaClassUtil.isTargetChildClass(simpleName, customRequestField.getOwnerClassName()) && (customRequestField.isIgnore()) && !isResp) { + if (customRequestField != null && JavaClassUtil.isTargetChildClass(simpleName, customRequestField.getOwnerClassName()) + && (customRequestField.isIgnore()) && !isResp) { continue; } an: @@ -220,6 +222,16 @@ public class ParamsBuildHelper { break doc; } } + // cover response value + if (Objects.nonNull(customResponseField) && isResp && Objects.nonNull(customResponseField.getValue()) + && JavaClassUtil.isTargetChildClass(simpleName, customResponseField.getOwnerClassName())) { + fieldValue = String.valueOf(customResponseField.getValue()); + } + // cover request value + if (Objects.nonNull(customRequestField) && !isResp && Objects.nonNull(customRequestField.getValue()) + && JavaClassUtil.isTargetChildClass(simpleName, customRequestField.getOwnerClassName())) { + fieldValue = String.valueOf(customRequestField.getValue()); + } //cover required if (customRequestField != null && !isResp && JavaClassUtil.isTargetChildClass(simpleName, customRequestField.getOwnerClassName()) && customRequestField.isRequire()) { @@ -354,11 +366,11 @@ public class ParamsBuildHelper { String gicName = genericMap.get(valType); if (!JavaClassValidateUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) { paramList.addAll(buildParams(gicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else { paramList.addAll(buildParams(valType, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } } else if (JavaClassValidateUtil.isCollection(subTypeName)) { @@ -389,11 +401,11 @@ public class ParamsBuildHelper { String gicName = genericMap.get(gName) != null ? genericMap.get(gName) : globGicName[0]; if (!JavaClassValidateUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) { paramList.addAll(buildParams(gicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else { paramList.addAll(buildParams(gName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } } else { @@ -428,25 +440,25 @@ public class ParamsBuildHelper { String gName = DocClassUtil.getSimpleGicName(gicName)[0]; if (!JavaClassValidateUtil.isPrimitive(gName)) { paramList.addAll(buildParams(gName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else if (JavaClassValidateUtil.isMap(simple)) { String valType = DocClassUtil.getMapKeyValueType(gicName)[1]; if (!JavaClassValidateUtil.isPrimitive(valType)) { paramList.addAll(buildParams(valType, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else { paramList.addAll(buildParams(gicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else { paramList.addAll(buildParams(gicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else { paramList.addAll(buildParams(subTypeName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } } else if (JavaClassValidateUtil.isArray(subTypeName)) { @@ -455,14 +467,14 @@ public class ParamsBuildHelper { //do nothing } else if (!JavaClassValidateUtil.isPrimitive(fieldGicName)) { paramList.addAll(buildParams(fieldGicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } else if (simpleName.equals(subTypeName)) { //do nothing } else { if (!javaClass.isEnum()) { paramList.addAll(buildParams(fieldGicName, preBuilder.toString(), nextLevel, isRequired, - responseFieldMap, isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); + isResp, registryClasses, projectBuilder, groupClasses, fieldPid, jsonRequest)); } } } diff --git a/src/main/java/com/power/doc/model/ApiConfig.java b/src/main/java/com/power/doc/model/ApiConfig.java index 0502bb9..15df1f3 100644 --- a/src/main/java/com/power/doc/model/ApiConfig.java +++ b/src/main/java/com/power/doc/model/ApiConfig.java @@ -25,10 +25,7 @@ package com.power.doc.model; import com.power.common.util.CollectionUtil; import com.power.doc.constants.DocLanguage; import com.power.doc.model.rpc.RpcApiDependency; -import com.power.doc.model.torna.DebugEnv; -import java.util.Collection; -import java.util.Collections; import java.util.List; import java.util.Objects; import java.util.stream.Collectors; @@ -253,19 +250,22 @@ public class ApiConfig { /** * request ignore param - * @since 1.9.2 + * * @return + * @since 1.9.2 */ private List ignoreRequestParams; /** * display actual type of generic + * * @since 1.9.6 */ private boolean displayActualType; /** * Support Spring MVC ResponseBodyAdvice + * * @since 1.9.8 */ private BodyAdvice responseBodyAdvice; @@ -284,6 +284,7 @@ public class ApiConfig { /** * Spring MVC url suffix + * * @since 2.1.0 */ private String urlSuffix; @@ -329,7 +330,7 @@ public class ApiConfig { /** * 推送人 */ - private String author; + private String author; public String getAuthor() { return author; @@ -347,42 +348,6 @@ public class ApiConfig { this.tornaDebug = tornaDebug; } - public void setSourceCodePaths(List sourceCodePaths) { - this.sourceCodePaths = sourceCodePaths; - } - - public void setRequestHeaders(List requestHeaders) { - this.requestHeaders = requestHeaders; - } - - public void setCustomResponseFields(List customResponseFields) { - this.customResponseFields = customResponseFields; - } - - public void setRevisionLogs(List revisionLogs) { - this.revisionLogs = revisionLogs; - } - - public void setDataDictionaries(List dataDictionaries) { - this.dataDictionaries = dataDictionaries; - } - - public void setErrorCodeDictionaries(List errorCodeDictionaries) { - this.errorCodeDictionaries = errorCodeDictionaries; - } - - public void setApiObjectReplacements(List apiObjectReplacements) { - this.apiObjectReplacements = apiObjectReplacements; - } - - public void setRpcApiDependencies(List rpcApiDependencies) { - this.rpcApiDependencies = rpcApiDependencies; - } - - public void setApiConstants(List apiConstants) { - this.apiConstants = apiConstants; - } - public String getAppKey() { return appKey; } @@ -443,6 +408,10 @@ public class ApiConfig { return requestHeaders; } + public void setRequestHeaders(List requestHeaders) { + this.requestHeaders = requestHeaders; + } + public void setRequestHeaders(ApiReqHeader... requestHeaders) { this.requestHeaders = CollectionUtil.asList(requestHeaders); this.requestHeaders.stream().map(header -> header.setDesc(header.getDesc() + "(Global)")) @@ -453,11 +422,14 @@ public class ApiConfig { return customResponseFields; } + public void setCustomResponseFields(List customResponseFields) { + this.customResponseFields = customResponseFields; + } + public void setCustomResponseFields(CustomField... customResponseFields) { this.customResponseFields = CollectionUtil.asList(customResponseFields); } - public List getErrorCodes() { return errorCodes; } @@ -470,6 +442,10 @@ public class ApiConfig { return sourceCodePaths; } + public void setSourceCodePaths(List sourceCodePaths) { + this.sourceCodePaths = sourceCodePaths; + } + public void setSourceCodePaths(SourceCodePath... sourcePaths) { this.sourceCodePaths = CollectionUtil.asList(sourcePaths); } @@ -494,11 +470,14 @@ public class ApiConfig { return revisionLogs; } + public void setRevisionLogs(List revisionLogs) { + this.revisionLogs = revisionLogs; + } + public void setRevisionLogs(RevisionLog... revisionLogs) { this.revisionLogs = CollectionUtil.asList(revisionLogs); } - public boolean isMd5EncryptedHtmlName() { return md5EncryptedHtmlName; } @@ -527,6 +506,10 @@ public class ApiConfig { return dataDictionaries; } + public void setDataDictionaries(List dataDictionaries) { + this.dataDictionaries = dataDictionaries; + } + public void setDataDictionaries(ApiDataDictionary... dataDictConfigs) { this.dataDictionaries = CollectionUtil.asList(dataDictConfigs); } @@ -544,6 +527,10 @@ public class ApiConfig { return errorCodeDictionaries; } + public void setErrorCodeDictionaries(List errorCodeDictionaries) { + this.errorCodeDictionaries = errorCodeDictionaries; + } + public void setErrorCodeDictionaries(ApiErrorCodeDictionary... errorCodeDictConfigs) { this.errorCodeDictionaries = CollectionUtil.asList(errorCodeDictConfigs); } @@ -552,6 +539,10 @@ public class ApiConfig { return apiObjectReplacements; } + public void setApiObjectReplacements(List apiObjectReplacements) { + this.apiObjectReplacements = apiObjectReplacements; + } + public void setApiObjectReplacements(ApiObjectReplacement... apiObjectReplaces) { this.apiObjectReplacements = CollectionUtil.asList(apiObjectReplaces); } @@ -560,6 +551,10 @@ public class ApiConfig { return rpcApiDependencies; } + public void setRpcApiDependencies(List rpcApiDependencies) { + this.rpcApiDependencies = rpcApiDependencies; + } + public void setRpcApiDependencies(RpcApiDependency... rpcApiDependencies) { this.rpcApiDependencies = CollectionUtil.asList(rpcApiDependencies); } @@ -568,6 +563,10 @@ public class ApiConfig { return apiConstants; } + public void setApiConstants(List apiConstants) { + this.apiConstants = apiConstants; + } + public void setApiConstants(ApiConstant... apiConstants) { this.apiConstants = CollectionUtil.asList(apiConstants); } @@ -788,6 +787,7 @@ public class ApiConfig { this.customRequestFields = customRequestFields; return this; } + public void setCustomRequestFields(CustomField... customRequestFields) { this.customRequestFields = CollectionUtil.asList(customRequestFields); } diff --git a/src/main/java/com/power/doc/model/ApiErrorCodeDictionary.java b/src/main/java/com/power/doc/model/ApiErrorCodeDictionary.java index 7a622bc..c358b99 100644 --- a/src/main/java/com/power/doc/model/ApiErrorCodeDictionary.java +++ b/src/main/java/com/power/doc/model/ApiErrorCodeDictionary.java @@ -52,7 +52,7 @@ public class ApiErrorCodeDictionary { return new ApiErrorCodeDictionary(); } - public static ApiErrorCodeDictionary builder(){ + public static ApiErrorCodeDictionary builder() { return new ApiErrorCodeDictionary(); } diff --git a/src/main/java/com/power/doc/model/ApiMethodReqParam.java b/src/main/java/com/power/doc/model/ApiMethodReqParam.java index 8700a1f..b8b7d81 100644 --- a/src/main/java/com/power/doc/model/ApiMethodReqParam.java +++ b/src/main/java/com/power/doc/model/ApiMethodReqParam.java @@ -44,7 +44,7 @@ public class ApiMethodReqParam { */ private List requestParams; - public static ApiMethodReqParam builder(){ + public static ApiMethodReqParam builder() { return new ApiMethodReqParam(); } diff --git a/src/main/java/com/power/doc/model/ApiObjectReplacement.java b/src/main/java/com/power/doc/model/ApiObjectReplacement.java index 7f08d76..85c5beb 100644 --- a/src/main/java/com/power/doc/model/ApiObjectReplacement.java +++ b/src/main/java/com/power/doc/model/ApiObjectReplacement.java @@ -31,7 +31,7 @@ public class ApiObjectReplacement { private String replacementClassName; - public static ApiObjectReplacement builder(){ + public static ApiObjectReplacement builder() { return new ApiObjectReplacement(); } diff --git a/src/main/java/com/power/doc/model/ApiParam.java b/src/main/java/com/power/doc/model/ApiParam.java index 26c0319..4cb81f8 100644 --- a/src/main/java/com/power/doc/model/ApiParam.java +++ b/src/main/java/com/power/doc/model/ApiParam.java @@ -25,7 +25,6 @@ package com.power.doc.model; import com.power.doc.model.torna.EnumInfo; import java.util.List; -import java.util.Map; /** * @author yu 2019/9/27. @@ -105,6 +104,10 @@ public class ApiParam { */ private String maxLength; + public static ApiParam of() { + return new ApiParam(); + } + public List getEnumInfo() { return enumInfo; } @@ -114,10 +117,6 @@ public class ApiParam { return this; } - public static ApiParam of(){ - return new ApiParam(); - } - public String getField() { return field; } @@ -185,6 +184,11 @@ public class ApiParam { return children; } + public ApiParam setChildren(List children) { + this.children = children; + return this; + } + public boolean isPathParam() { return pathParam; } @@ -203,11 +207,6 @@ public class ApiParam { return this; } - public ApiParam setChildren(List children) { - this.children = children; - return this; - } - public String getValue() { return value; } diff --git a/src/main/java/com/power/doc/model/BodyAdvice.java b/src/main/java/com/power/doc/model/BodyAdvice.java index 1e2a726..0aec83a 100644 --- a/src/main/java/com/power/doc/model/BodyAdvice.java +++ b/src/main/java/com/power/doc/model/BodyAdvice.java @@ -23,8 +23,8 @@ package com.power.doc.model; /** - * @since 1.9.8 * @author yu 2020/11/5. + * @since 1.9.8 */ public class BodyAdvice { @@ -34,7 +34,7 @@ public class BodyAdvice { private String dataField; - public static BodyAdvice builder(){ + public static BodyAdvice builder() { return new BodyAdvice(); } diff --git a/src/main/java/com/power/doc/model/CustomField.java b/src/main/java/com/power/doc/model/CustomField.java index 61410be..adefabf 100644 --- a/src/main/java/com/power/doc/model/CustomField.java +++ b/src/main/java/com/power/doc/model/CustomField.java @@ -49,6 +49,10 @@ public class CustomField { private boolean ignore; + public static CustomField builder() { + return new CustomField(); + } + public boolean isRequire() { return require; } @@ -57,9 +61,6 @@ public class CustomField { this.require = require; return this; } - public static CustomField builder() { - return new CustomField(); - } public String getName() { return name; diff --git a/src/main/java/com/power/doc/model/DocJavaField.java b/src/main/java/com/power/doc/model/DocJavaField.java index fd0673b..7090b40 100644 --- a/src/main/java/com/power/doc/model/DocJavaField.java +++ b/src/main/java/com/power/doc/model/DocJavaField.java @@ -32,7 +32,7 @@ import java.util.List; /** * @author yu 2020/3/19. */ -public class DocJavaField { +public class DocJavaField { /** * field info diff --git a/src/main/java/com/power/doc/model/DocJavaMethod.java b/src/main/java/com/power/doc/model/DocJavaMethod.java index 540c226..c480454 100644 --- a/src/main/java/com/power/doc/model/DocJavaMethod.java +++ b/src/main/java/com/power/doc/model/DocJavaMethod.java @@ -28,20 +28,20 @@ import com.thoughtworks.qdox.model.JavaType; import java.util.Map; /** - * @since 1.9.8 * @author yu 2020/10/30. + * @since 1.9.8 */ public class DocJavaMethod { private JavaMethod javaMethod; - private Map returnSchema; + private Map returnSchema; - private Map requestSchema; + private Map requestSchema; private Map actualTypesMap; - public static DocJavaMethod builder(){ + public static DocJavaMethod builder() { return new DocJavaMethod(); } @@ -63,11 +63,11 @@ public class DocJavaMethod { return this; } - public Map getReturnSchema() { + public Map getReturnSchema() { return returnSchema; } - public DocJavaMethod setReturnSchema(Map returnSchema) { + public DocJavaMethod setReturnSchema(Map returnSchema) { this.returnSchema = returnSchema; return this; } diff --git a/src/main/java/com/power/doc/model/JavaMethodDoc.java b/src/main/java/com/power/doc/model/JavaMethodDoc.java index b8adb88..8b38c96 100644 --- a/src/main/java/com/power/doc/model/JavaMethodDoc.java +++ b/src/main/java/com/power/doc/model/JavaMethodDoc.java @@ -31,19 +31,16 @@ public class JavaMethodDoc { /** * methodId handled by md5 - * */ private String methodId; /** * method name - * */ private String name; /** * method order - * */ private int order; diff --git a/src/main/java/com/power/doc/model/postman/InfoBean.java b/src/main/java/com/power/doc/model/postman/InfoBean.java index 47ba732..a26826d 100644 --- a/src/main/java/com/power/doc/model/postman/InfoBean.java +++ b/src/main/java/com/power/doc/model/postman/InfoBean.java @@ -38,7 +38,7 @@ public class InfoBean { public InfoBean(String name) { if (StringUtils.isBlank(name)) { - this.name = "smart-doc " + DateTimeUtil.long2Str(System.currentTimeMillis(),DateTimeUtil.DATE_FORMAT_SECOND); + this.name = "smart-doc " + DateTimeUtil.long2Str(System.currentTimeMillis(), DateTimeUtil.DATE_FORMAT_SECOND); } else { this.name = name; } diff --git a/src/main/java/com/power/doc/model/rpc/RpcApiDependency.java b/src/main/java/com/power/doc/model/rpc/RpcApiDependency.java index 0dc581e..aeabd9b 100644 --- a/src/main/java/com/power/doc/model/rpc/RpcApiDependency.java +++ b/src/main/java/com/power/doc/model/rpc/RpcApiDependency.java @@ -66,10 +66,10 @@ public class RpcApiDependency { @Override public String toString() { - return ""+"\r"+ - "\t"+"" + groupId + "" +"\n"+ - "\t"+"" + artifactId + "" +"\n"+ - "\t"+ "" + version + "" +""+ - "\r"+""; + return "" + "\r" + + "\t" + "" + groupId + "" + "\n" + + "\t" + "" + artifactId + "" + "\n" + + "\t" + "" + version + "" + "" + + "\r" + ""; } } diff --git a/src/main/java/com/power/doc/model/rpc/RpcApiDoc.java b/src/main/java/com/power/doc/model/rpc/RpcApiDoc.java index 4df116a..b80e8aa 100644 --- a/src/main/java/com/power/doc/model/rpc/RpcApiDoc.java +++ b/src/main/java/com/power/doc/model/rpc/RpcApiDoc.java @@ -22,7 +22,6 @@ */ package com.power.doc.model.rpc; -import com.power.common.util.StringUtil; import com.power.doc.model.JavaMethodDoc; import java.util.List; @@ -185,7 +184,7 @@ public class RpcApiDoc implements Comparable { } public String getLink() { - return desc.replace(" ","_").toLowerCase(); + return desc.replace(" ", "_").toLowerCase(); } public void setLink(String link) { diff --git a/src/main/java/com/power/doc/model/torna/Apis.java b/src/main/java/com/power/doc/model/torna/Apis.java index f29e60f..b99abdc 100644 --- a/src/main/java/com/power/doc/model/torna/Apis.java +++ b/src/main/java/com/power/doc/model/torna/Apis.java @@ -138,6 +138,10 @@ public class Apis { return headerParams; } + public void setHeaderParams(List headerParams) { + this.headerParams = headerParams; + } + public List getPathParams() { return pathParams; } @@ -147,10 +151,6 @@ public class Apis { return this; } - public void setHeaderParams(List headerParams) { - this.headerParams = headerParams; - } - public List getResponseParams() { return responseParams; } @@ -171,6 +171,10 @@ public class Apis { return items; } + public void setItems(List items) { + this.items = items; + } + public DubboInfo getDubboInfo() { return dubboInfo; } @@ -178,8 +182,4 @@ public class Apis { public void setDubboInfo(DubboInfo dubboInfo) { this.dubboInfo = dubboInfo; } - - public void setItems(List items) { - this.items = items; - } } diff --git a/src/main/java/com/power/doc/model/torna/DubboInfo.java b/src/main/java/com/power/doc/model/torna/DubboInfo.java index bec357d..1be5d69 100644 --- a/src/main/java/com/power/doc/model/torna/DubboInfo.java +++ b/src/main/java/com/power/doc/model/torna/DubboInfo.java @@ -10,9 +10,10 @@ public class DubboInfo { private String protocol; private String dependency; - public DubboInfo builder(){ + public DubboInfo builder() { return new DubboInfo(); } + public String getInterfaceName() { return interfaceName; } diff --git a/src/main/java/com/power/doc/model/torna/EnumInfo.java b/src/main/java/com/power/doc/model/torna/EnumInfo.java index 5c72c8a..1bb76a0 100644 --- a/src/main/java/com/power/doc/model/torna/EnumInfo.java +++ b/src/main/java/com/power/doc/model/torna/EnumInfo.java @@ -29,18 +29,18 @@ import java.util.List; **/ public class EnumInfo { /** - * "enumInfo": { - * "name": "支付枚举", - * "description": "支付状态", - * "items": [ - * { - * "name": "WAIT_PAY", - * "type": "string", - * "value": "0", - * "description": "未支付" - * } - * ] - * } + * "enumInfo": { + * "name": "支付枚举", + * "description": "支付状态", + * "items": [ + * { + * "name": "WAIT_PAY", + * "type": "string", + * "value": "0", + * "description": "未支付" + * } + * ] + * } */ private String name; private String description; diff --git a/src/main/java/com/power/doc/model/torna/Item.java b/src/main/java/com/power/doc/model/torna/Item.java index f1a809f..1dd1e26 100644 --- a/src/main/java/com/power/doc/model/torna/Item.java +++ b/src/main/java/com/power/doc/model/torna/Item.java @@ -28,11 +28,11 @@ package com.power.doc.model.torna; public class Item { /** * { - * * "name": "WAIT_PAY", - * * "type": "string", - * * "value": "0", - * * "description": "未支付" - * * } + * * "name": "WAIT_PAY", + * * "type": "string", + * * "value": "0", + * * "description": "未支付" + * * } */ private String name; private String type; diff --git a/src/main/java/com/power/doc/model/torna/TornaApi.java b/src/main/java/com/power/doc/model/torna/TornaApi.java index d269bcd..3bb6816 100644 --- a/src/main/java/com/power/doc/model/torna/TornaApi.java +++ b/src/main/java/com/power/doc/model/torna/TornaApi.java @@ -30,13 +30,13 @@ import java.util.List; public class TornaApi { /** - * "debugEnvs": [ - * { - * "name": "测试环境", - * "url": "http://10.1.30.165:2222" - * } - * ], - * "apis": [ + * "debugEnvs": [ + * { + * "name": "测试环境", + * "url": "http://10.1.30.165:2222" + * } + * ], + * "apis": [ */ List debugEnvs; List apis; diff --git a/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java b/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java index ed0c723..4a07701 100644 --- a/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java +++ b/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java @@ -29,7 +29,8 @@ import java.net.URLDecoder; import java.util.HashMap; /** - * torna请求日志信息 + * torna请求日志信息 + * * @author: xingzi 2021/3/20 22:11 **/ public class TornaRequestInfo { @@ -48,9 +49,10 @@ public class TornaRequestInfo { return this; } - public TornaRequestInfo of(){ + public TornaRequestInfo of() { return this; } + public String getCode() { return code; } @@ -87,7 +89,7 @@ public class TornaRequestInfo { return this; } - public String buildInfo(){ + public String buildInfo() { StringBuilder sb = new StringBuilder(); sb.append("---------------------------START---------------------------\n") .append("接口名: ") @@ -97,13 +99,13 @@ public class TornaRequestInfo { .append(TornaConstants.GSON.toJson(requestInfo)) .append("\n") .append("返回结果: \n") - .append(TornaConstants.GSON.fromJson(responseInfo,HashMap.class)) + .append(TornaConstants.GSON.fromJson(responseInfo, HashMap.class)) .append("\n") .append("---------------------------END---------------------------\n"); try { - return URLDecoder.decode(sb.toString(),"utf-8"); + return URLDecoder.decode(sb.toString(), "utf-8"); } catch (UnsupportedEncodingException e) { e.printStackTrace(); return ""; diff --git a/src/main/java/com/power/doc/template/IDocBuildTemplate.java b/src/main/java/com/power/doc/template/IDocBuildTemplate.java index 8b3b413..47ddaef 100644 --- a/src/main/java/com/power/doc/template/IDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/IDocBuildTemplate.java @@ -132,8 +132,8 @@ public interface IDocBuildTemplate { docJavaMethod.setReturnSchema(OpenApiSchemaUtil.arrayTypeSchema(gicName)); return new ArrayList<>(0); } - return ParamsBuildHelper.buildParams(gicName, "", 0, null, projectBuilder.getCustomRespFieldMap(), - Boolean.TRUE, new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); + return ParamsBuildHelper.buildParams(gicName, "", 0, null, Boolean.TRUE, + new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); } else { return new ArrayList<>(0); } @@ -147,12 +147,12 @@ public interface IDocBuildTemplate { docJavaMethod.setReturnSchema(OpenApiSchemaUtil.mapTypeSchema(keyValue[1])); return new ArrayList<>(0); } - return ParamsBuildHelper.buildParams(keyValue[1], "", 0, null, projectBuilder.getCustomRespFieldMap(), - Boolean.TRUE, new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); + return ParamsBuildHelper.buildParams(keyValue[1], "", 0, null, Boolean.TRUE, + new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); } if (StringUtil.isNotEmpty(returnType)) { - return ParamsBuildHelper.buildParams(returnType, "", 0, null, projectBuilder.getCustomRespFieldMap(), - Boolean.TRUE, new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); + return ParamsBuildHelper.buildParams(returnType, "", 0, null, Boolean.TRUE, + new HashMap<>(), projectBuilder, null, 0, Boolean.FALSE); } return new ArrayList<>(0); } diff --git a/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java b/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java index b5ca792..a3757ab 100644 --- a/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java @@ -30,7 +30,10 @@ import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.DocTags; import com.power.doc.constants.DubboAnnotationConstants; import com.power.doc.helper.ParamsBuildHelper; -import com.power.doc.model.*; +import com.power.doc.model.ApiConfig; +import com.power.doc.model.ApiParam; +import com.power.doc.model.DocJavaMethod; +import com.power.doc.model.JavaMethodDoc; import com.power.doc.model.rpc.RpcApiDoc; import com.power.doc.utils.DocClassUtil; import com.power.doc.utils.DocUtil; @@ -164,7 +167,6 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { private List requestParams(final JavaMethod javaMethod, ProjectDocConfigBuilder builder) { boolean isStrict = builder.getApiConfig().isStrict(); boolean isShowJavaType = builder.getApiConfig().getShowJavaType(); - Map responseFieldMap = new HashMap<>(); String className = javaMethod.getDeclaringClass().getCanonicalName(); Map paramTagMap = DocUtil.getParamsComments(javaMethod, DocTags.PARAM, className); List parameterList = javaMethod.getParameters(); @@ -203,7 +205,7 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { paramList.add(param); } else { paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", - responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); + Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); } } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { ApiParam param = ApiParam.of().setField(paramName) @@ -219,14 +221,14 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { } String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", - responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); + Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); } else if (javaClass.isEnum()) { ApiParam param = ApiParam.of().setField(paramName) .setType("Enum").setDesc(comment).setRequired(true).setVersion(DocGlobalConstants.DEFAULT_VERSION); paramList.add(param); } else { paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", - responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); + Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); } } return paramList; diff --git a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java index b5fd553..ff32e65 100644 --- a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java @@ -55,13 +55,11 @@ import static com.power.doc.constants.DocTags.IGNORE_REQUEST_BODY_ADVICE; public class SpringBootDocBuildTemplate implements IDocBuildTemplate { private static Logger log = Logger.getLogger(SpringBootDocBuildTemplate.class.getName()); - - private List headers; - /** * api index */ private final AtomicInteger atomicInteger = new AtomicInteger(1); + private List headers; @Override public List getApiData(ProjectDocConfigBuilder projectBuilder) { @@ -715,7 +713,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { if (requestBodyCounter > 0) { //for json paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], DocGlobalConstants.EMPTY, 0, - "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, + "true", Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.TRUE)); } else { throw new RuntimeException("Spring MVC can't support binding Collection on method " @@ -765,7 +763,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { } } else { paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], DocGlobalConstants.EMPTY, 0, - "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), + "true", Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); } @@ -786,7 +784,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { paramList.add(param); } else { paramList.addAll(ParamsBuildHelper.buildParams(typeName, DocGlobalConstants.EMPTY, 0, - "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); + "true", Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0, Boolean.FALSE)); } } List pathParams = new ArrayList<>(); diff --git a/src/main/java/com/power/doc/utils/ApiParamTreeUtil.java b/src/main/java/com/power/doc/utils/ApiParamTreeUtil.java index d1a621a..c5f0825 100644 --- a/src/main/java/com/power/doc/utils/ApiParamTreeUtil.java +++ b/src/main/java/com/power/doc/utils/ApiParamTreeUtil.java @@ -27,7 +27,6 @@ import com.power.doc.model.ApiParam; import java.util.ArrayList; import java.util.List; -import java.util.Objects; /** * @author yu 2020/8/8. diff --git a/src/main/java/com/power/doc/utils/CurlUtil.java b/src/main/java/com/power/doc/utils/CurlUtil.java index b852be0..a586fa6 100644 --- a/src/main/java/com/power/doc/utils/CurlUtil.java +++ b/src/main/java/com/power/doc/utils/CurlUtil.java @@ -41,7 +41,7 @@ public class CurlUtil { if (request.getUrl().indexOf("https") == 0) { sb.append(" -k"); } - if (StringUtil.isNotEmpty(request.getContentType())&& + if (StringUtil.isNotEmpty(request.getContentType()) && !DocGlobalConstants.URL_CONTENT_TYPE.equals(request.getContentType())) { sb.append(" -H"); sb.append(" 'Content-Type: ").append(request.getContentType()).append("'"); diff --git a/src/main/java/com/power/doc/utils/JavaClassUtil.java b/src/main/java/com/power/doc/utils/JavaClassUtil.java index cd81a42..466766b 100644 --- a/src/main/java/com/power/doc/utils/JavaClassUtil.java +++ b/src/main/java/com/power/doc/utils/JavaClassUtil.java @@ -495,14 +495,14 @@ public class JavaClassUtil { } } - public static boolean isTargetChildClass(String sourceClass,String targetClass){ + public static boolean isTargetChildClass(String sourceClass, String targetClass) { try { - if(sourceClass.equals(targetClass)){ + if (sourceClass.equals(targetClass)) { return true; } Class c = Class.forName(sourceClass); - while (c != null){ - if(c.getName().equals(targetClass)){ + while (c != null) { + if (c.getName().equals(targetClass)) { return true; } c = c.getSuperclass(); diff --git a/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java b/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java index b93fb73..c0a98ba 100644 --- a/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java +++ b/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java @@ -216,7 +216,7 @@ public class JavaClassValidateUtil { /** * ignore param of spring mvc * - * @param paramType param type name + * @param paramType param type name * @param ignoreParams ignore param list * @return boolean */ @@ -261,10 +261,11 @@ public class JavaClassValidateUtil { /** * check file + * * @param typeName type name * @return boolean */ - public static boolean isFile(String typeName){ + public static boolean isFile(String typeName) { switch (typeName) { case "org.springframework.web.multipart.MultipartFile": case "org.springframework.web.multipart.MultipartFile[]": @@ -280,6 +281,7 @@ public class JavaClassValidateUtil { /** * check reactor param + * * @param typeName class name * @return boolean */ diff --git a/src/main/java/com/power/doc/utils/JavaFieldUtil.java b/src/main/java/com/power/doc/utils/JavaFieldUtil.java index 37bf200..d22ddee 100644 --- a/src/main/java/com/power/doc/utils/JavaFieldUtil.java +++ b/src/main/java/com/power/doc/utils/JavaFieldUtil.java @@ -46,10 +46,9 @@ public class JavaFieldUtil { } /** - * - * @param data0 data0 + * @param data0 data0 * @param typeSimpleName typeName - * @param customField config field + * @param customField config field */ public static void buildCustomField(StringBuilder data0, String typeSimpleName, CustomField customField) { Object val = customField.getValue(); diff --git a/src/main/java/com/power/doc/utils/OpenApiSchemaUtil.java b/src/main/java/com/power/doc/utils/OpenApiSchemaUtil.java index 11585fb..7318607 100644 --- a/src/main/java/com/power/doc/utils/OpenApiSchemaUtil.java +++ b/src/main/java/com/power/doc/utils/OpenApiSchemaUtil.java @@ -31,13 +31,13 @@ import java.util.Map; */ public class OpenApiSchemaUtil { - public static Map primaryTypeSchema(String primaryType){ + public static Map primaryTypeSchema(String primaryType) { Map map = new HashMap<>(); map.put("type", DocClassUtil.processTypeNameForParams(primaryType)); return map; } - public static Map mapTypeSchema(String primaryType){ + public static Map mapTypeSchema(String primaryType) { Map map = new LinkedHashMap<>(); map.put("type", "object"); Map items = new HashMap<>(); @@ -46,7 +46,7 @@ public class OpenApiSchemaUtil { return map; } - public static Map arrayTypeSchema(String primaryType){ + public static Map arrayTypeSchema(String primaryType) { Map map = new HashMap<>(); map.put("type", "array"); Map items = new HashMap<>(); diff --git a/src/main/resources/default.json b/src/main/resources/default.json index f0ecc90..7b01fd1 100644 --- a/src/main/resources/default.json +++ b/src/main/resources/default.json @@ -4,7 +4,7 @@ "allInOne": true, "outPath": "D://md2", "coverOld": true, - "allInOneDocFileName":"demoProject.html", + "allInOneDocFileName": "demoProject.html", "packageFilters": "", "md5EncryptedHtmlName": false, "projectName": "smart-doc", diff --git a/src/main/resources/template/dubbo/Dubbo.md b/src/main/resources/template/dubbo/Dubbo.md index 9315791..6434ff4 100644 --- a/src/main/resources/template/dubbo/Dubbo.md +++ b/src/main/resources/template/dubbo/Dubbo.md @@ -1,4 +1,3 @@ - # ${desc} **URI:** ${uri} @@ -10,13 +9,15 @@ **Author:** ${author} **Version:** ${version} -<% -for(doc in list){ -%> +<% for(doc in list){ %> <%if(doc.deprecated){%> + ## ~~${doc.desc}~~ + <%}else{%> + ## ${doc.desc} + <%}%> **Definition：** ${doc.methodDefinition} @@ -32,9 +33,8 @@ for(doc in list){ Parameter|Type|Description|Required|Since ---|---|---|---|--- -<% -for(param in doc.requestParams){ -%> + +<% for(param in doc.requestParams){ %> ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} <%}%> <%}%> @@ -44,9 +44,8 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} Field | Type|Description|Since ---|---|---|--- -<% -for(param in doc.responseParams){ -%> + +<% for(param in doc.responseParams){ %> ${param.field}|${param.type}|${param.desc}|${param.version} <%}%> <%}%> diff --git a/src/main/resources/template/dubbo/DubboAllInOne.md b/src/main/resources/template/dubbo/DubboAllInOne.md index 0fc59e2..561c9fc 100644 --- a/src/main/resources/template/dubbo/DubboAllInOne.md +++ b/src/main/resources/template/dubbo/DubboAllInOne.md @@ -1,18 +1,18 @@ <%if(isNotEmpty(projectName)){%> + # ${projectName} + <%}%> <%if(isNotEmpty(revisionLogList)){%> -Version | Update Time | Status | Author | Description ----|---|---|---|--- -<% -for(revisionLog in revisionLogList){ -%> +Version | Update Time | Status | Author | Description ---|---|---|---|--- +<% for(revisionLog in revisionLogList){ %> ${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks} <%}%> <%}%> <%if(isNotEmpty(dependencyList)){%> + ## Add dependency ``` @@ -27,17 +27,19 @@ for(dependency in dependencyList){ <%}%> ``` + <%if(isNotEmpty(consumerConfigExample)){%> Consumer config + ``` ${consumerConfigExample} ``` + <%}%> <%}%> -<% -for(api in apiDocList){ -%> +<% for(api in apiDocList){ %> + ## ${api.desc} **URI:** ${api.uri} @@ -49,13 +51,15 @@ for(api in apiDocList){ **Author:** ${api.author} **Version:** ${api.version} -<% -for(doc in api.list){ -%> +<% for(doc in api.list){ %> <%if(doc.deprecated){%> + ### ~~${doc.desc}~~ + <%}else{%> + ### ${doc.desc} + <%}%> **Definition：** ${doc.methodDefinition} @@ -71,9 +75,8 @@ for(doc in api.list){ Parameter|Type|Description|Required|Since ---|---|---|---|--- -<% -for(param in doc.requestParams){ -%> + +<% for(param in doc.requestParams){ %> ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} <%}%> <%}%> @@ -83,20 +86,20 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} Field | Type|Description|Since ---|---|---|--- -<% -for(param in doc.responseParams){ -%> + +<% for(param in doc.responseParams){ %> ${param.field}|${param.type}|${param.desc}|${param.version} <%}%> <%}%> <%if(isNotEmpty(errorCodeList)){%> + ## ${errorListTitle} + Error code |Description ---|--- -<% -for(error in errorCodeList){ -%> + +<% for(error in errorCodeList){ %> ${error.value}|${error.desc} <%}%> <%}%> diff --git a/src/main/resources/template/dubbo/DubboApiDependency.md b/src/main/resources/template/dubbo/DubboApiDependency.md index c0f18f9..741b5fc 100644 --- a/src/main/resources/template/dubbo/DubboApiDependency.md +++ b/src/main/resources/template/dubbo/DubboApiDependency.md @@ -12,9 +12,12 @@ for(dependency in dependencyList){ <%}%> ``` + <%if(isNotEmpty(consumerConfigExample)){%> Consumer config + ``` ${consumerConfigExample} ``` + <%}%> \ No newline at end of file diff --git a/src/main/resources/template/dubbo/DubboApiDependencyEmpty.md b/src/main/resources/template/dubbo/DubboApiDependencyEmpty.md index 70b7d74..5636c9a 100644 --- a/src/main/resources/template/dubbo/DubboApiDependencyEmpty.md +++ b/src/main/resources/template/dubbo/DubboApiDependencyEmpty.md @@ -9,6 +9,7 @@ ``` Consumer config + ``` dubbo: registry: diff --git a/src/test/java/com/power/doc/ApiDocTest.java b/src/test/java/com/power/doc/ApiDocTest.java index 5d399cd..1178bbc 100644 --- a/src/test/java/com/power/doc/ApiDocTest.java +++ b/src/test/java/com/power/doc/ApiDocTest.java @@ -2,17 +2,12 @@ package com.power.doc; import com.power.common.util.DateTimeUtil; import com.power.doc.builder.HtmlApiDocBuilder; -import com.power.doc.builder.OpenApiBuilder; -import com.power.doc.builder.PostmanJsonBuilder; import com.power.doc.builder.TornaBuilder; -import com.power.doc.builder.rpc.RpcHtmlBuilder; -import com.power.doc.builder.rpc.RpcTornaBuilder; import com.power.doc.enums.OrderEnum; import com.power.doc.model.*; import com.power.doc.model.rpc.RpcApiDependency; import org.junit.Test; -import java.io.UnsupportedEncodingException; import java.util.ArrayList; import java.util.List; @@ -28,7 +23,7 @@ public class ApiDocTest { * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释 */ @Test - public void testBuilderControllersApi() { + public void testBuilderControllersApi() { List list = new ArrayList<>(); list.add("aa"); list.contains("aa"); @@ -42,7 +37,7 @@ public class ApiDocTest { config.setDebugEnvName("测试环境"); // config.setAuthor("test"); config.setDebugEnvUrl("http://127.0.0.1"); - //config.setTornaDebug(true); + //config.setTornaDebug(true); config.setAllInOne(true); config.setOutPath("d:\\md3"); @@ -81,7 +76,7 @@ public class ApiDocTest { .setName("sex").setDesc("性别").setIgnore(false).setValue("男").setRequire(true).setOwnerClassName("com.power.doc.entity.SimpleUser") - ); + ); config.setPackageFilters("com.power.doc.dubbo.*,com.power.doc.controller.UserController"); //非必须只有当setAllInOne设置为true时文档变更记录才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O config.setRevisionLogs( @@ -98,7 +93,7 @@ public class ApiDocTest { .setClassName("com.power.common.model.CommonResult")); config.setRpcApiDependencies(RpcApiDependency.builder().setGroupId("com.test").setArtifactId("test1").setVersion("1.0"), RpcApiDependency.builder().setGroupId("com.smart").setArtifactId("test").setVersion("1.1.1") - ); + ); long start = System.currentTimeMillis(); //TornaBuilder.buildApiDoc(config); @@ -106,7 +101,7 @@ public class ApiDocTest { HtmlApiDocBuilder.buildApiDoc(config); //RpcTornaBuilder.buildApiDoc(config); TornaBuilder.buildApiDoc(config); - // RpcHtmlBuilder.buildApiDoc(config); + // RpcHtmlBuilder.buildApiDoc(config); long end = System.currentTimeMillis(); DateTimeUtil.printRunTime(end, start); } diff --git a/src/test/java/com/power/doc/Main.java b/src/test/java/com/power/doc/Main.java index dd2deb7..a7c4f72 100644 --- a/src/test/java/com/power/doc/Main.java +++ b/src/test/java/com/power/doc/Main.java @@ -26,7 +26,7 @@ public class Main { public static void main(String[] args) { String artifactId = "ksharding-jdbc"; new HashMap<>(); - ConcurrentHashMap map = new ConcurrentHashMap<>(); + ConcurrentHashMap map = new ConcurrentHashMap<>(); map.size(); System.out.println(ignoreArtifactById(artifactId)); } diff --git a/src/test/java/com/power/doc/util/DocClassUtilTest.java b/src/test/java/com/power/doc/util/DocClassUtilTest.java index 100cb57..1ee8840 100644 --- a/src/test/java/com/power/doc/util/DocClassUtilTest.java +++ b/src/test/java/com/power/doc/util/DocClassUtilTest.java @@ -1,36 +1,35 @@ -package com.power.doc.util; - -import com.power.doc.model.ApiReturn; -import com.power.doc.utils.DocClassUtil; -import com.power.doc.utils.JavaClassValidateUtil; -import org.junit.Test; - -/** - * Description: - * DocUtil junit test - * - * @author yu 2018/06/16. - */ -public class DocClassUtilTest { - - @Test - public void testGetSimpleGicName() { - char me = 'k'; - String className = "com.power.doc.controller.Teacher,com.power.doc.controller.Teacher,com.power.doc.controller.Teacher>"; - String[] arr = DocClassUtil.getSimpleGicName(className); -// System.out.println("arr:"+ JSON.toJSONString(arr)); - } - - @Test - public void testIsPrimitive() { - String typeName = "java.time.LocalDateTime"; - System.out.println(JavaClassValidateUtil.isPrimitive(typeName)); - } - - @Test - public void testProcessReturnType() { - String typeName = "org.springframework.data.domain.Pageable"; - System.out.println(DocClassUtil.rewriteRequestParam(typeName)); - - } -} +package com.power.doc.util; + +import com.power.doc.utils.DocClassUtil; +import com.power.doc.utils.JavaClassValidateUtil; +import org.junit.Test; + +/** + * Description: + * DocUtil junit test + * + * @author yu 2018/06/16. + */ +public class DocClassUtilTest { + + @Test + public void testGetSimpleGicName() { + char me = 'k'; + String className = "com.power.doc.controller.Teacher,com.power.doc.controller.Teacher,com.power.doc.controller.Teacher>"; + String[] arr = DocClassUtil.getSimpleGicName(className); +// System.out.println("arr:"+ JSON.toJSONString(arr)); + } + + @Test + public void testIsPrimitive() { + String typeName = "java.time.LocalDateTime"; + System.out.println(JavaClassValidateUtil.isPrimitive(typeName)); + } + + @Test + public void testProcessReturnType() { + String typeName = "org.springframework.data.domain.Pageable"; + System.out.println(DocClassUtil.rewriteRequestParam(typeName)); + + } +}