tongchengopensource / smart-doc-maven-plugin Goto Github PK

The execute method of BaseDocsGeneratorMojo calls isAbsPath without checking if the input parameter is null. When the rpcConsumerConfig parameter is not set, it will also assemble an absolute path file, resulting in a non-existent file ending with the string "null". Subsequent attempts to open the file will throw an exception.
There are two places in this method where isAbsPath is called, and both have the issue of not checking if the input parameter is null.
BaseDocsGeneratorMojo的execute方法调用isAbsPath没有判断入参是否为null，没有配rpcConsumerConfig参数时也会拼绝对路径文件，拼出来的是以”null“字符串结尾的并不存在的文件，后续打开文件抛异常。
这个方法的两处isAbsPath调用都存在未判入参为null的问题。

Expected Behavior(您期望的结果)

其他模块包的枚举解析说明与本项目包的枚举解析一致

Current Behavior(当前结果)

其他模块包枚举作为请求或响应数据只读取了name内容
当前项目枚举解析后显示：

其他模块包解析后torna显示：

Possible Solution(bug解决建议)

其他模块包的枚举解析说明与本项目包的枚举解析一致

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

smart doc配置文件已开启: "inlineEnum": true
伪代码：

本项目定义枚举:
public enum MyProjectEnum {
        FIRST(1,"第一个值"), LAST(2, "第二个值");
        private final int key;
        private final String val;
        MyProjectEnum(int key, String val) {
            this.key = key;
            this.val = val;
        }
        public int getKey() {
            return this.key;
        }
        public String getVal(){
            return this.val;
        }
    }
其他项目定义枚举:
    public enum OtherProjectEnum {
        FIRST(1,"第一个值"), LAST(2, "第二个值");
        private final int key;
        private final String val;
        OtherProjectEnum(int key, String val) {
            this.key = key;
            this.val = val;
        }
        public int getKey() {
            return this.key;
        }
        public String getVal(){
            return this.val;
        }
    }
定义一个请求参数对象：
    public class Param{
        /**
         * 当前项目枚举
         */
        private MyProjectEnum myProject;
        /**
         * 其他项目枚举
         */
        private OtherProjectEnum otherObject;
        public MyProjectEnum getMyProject(){
            return myProject;
        }
        public OtherProjectEnum getOtherProject(){
            return otherObject;
        }
    }
Controller代码:
@RestController
public class MyController{
  @GetMapping("/test")
  public Ret<Param> getTest(@RequestBody Param param){
    return param;
  }
}
统一响应结构:
public class Ret<T>{
  private int code;
  private String msg;
  private T data;
  public Ret(int code, String msg, T data){
    this.code=code;
    this.msg=msg;
    this.data=data;
  }
}

Context(Bug影响描述)

使用其他包的枚举解析成openApiJson或者推送到torna都是显示不完整

Your Environment(您的使用环境)

• smart-doc version:
• smart-doc-maven-plugin version: 2.4.3
• maven version: Apache Maven 3.8.4

Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "12.3", arch: "aarch64", family: "mac"

smart-doc-maven-plugin 1.1.2pom引用的smart-doc版本还是1.8.9，与readme所说的1.9.0不一致

Expected Behavior(您期望的结果)

When making a POST request, the Chinese parameters in the request body should not be URLEncoded.
post请求的时候，请求体中的中文参数，不要被URLEncode。

Current Behavior(当前结果)

When initiating a POST request, the Chinese parameters in the request body are being URLEncoded, causing the backend interface to receive the parameters incorrectly.
发起post请求的时候，请求体的中文参数被URLEncode。导致后端接口接收参数错误。

Possible Solution(bug解决建议)

GET requests can encode parameters, but POST requests do not need to be encoded.
get请求可以把参数编码，但是post请求不用编码。

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

Context(Bug影响描述)

Your Environment(您的使用环境)

• smart-doc version:
• plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin): 2.5.3
• build tool version(maven or gradle):

[ERROR]
java.lang.ArrayIndexOutOfBoundsException: 1
at com.power.doc.helper.ParamsBuildHelper.buildParams (ParamsBuildHelper.java:317)
at com.power.doc.helper.ParamsBuildHelper.buildParams (ParamsBuildHelper.java:426)
at com.power.doc.helper.ParamsBuildHelper.buildParams (ParamsBuildHelper.java:406)
at com.power.doc.template.IDocBuildTemplate.buildReturnApiParams (IDocBuildTemplate.java:154)
at com.power.doc.template.SpringBootDocBuildTemplate.buildControllerMethod (SpringBootDocBuildTemplate.java:242)
at com.power.doc.template.SpringBootDocBuildTemplate.getApiData (SpringBootDocBuildTemplate.java:89)
at com.power.doc.builder.HtmlApiDocBuilder.buildApiDoc (HtmlApiDocBuilder.java:76)
at com.smartdoc.mojo.HtmlMojo.executeMojo (HtmlMojo.java:47)
at com.smartdoc.mojo.BaseDocsGeneratorMojo.execute (BaseDocsGeneratorMojo.java:145)
at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:137)
at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:210)
at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:156)
at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:148)
at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:117)
at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:81)
at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:56)
at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:128)
at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:305)
at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:192)
at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:105)
at org.apache.maven.cli.MavenCli.execute (MavenCli.java:957)
at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:289)
at org.apache.maven.cli.MavenCli.main (MavenCli.java:193)
at sun.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke (Method.java:498)
at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:282)
at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:225)
at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:406)
at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:347)
at org.codehaus.classworlds.Launcher.main (Launcher.java:47)

Expected Behavior(您期望的结果)

Normally, the comments from the public module and dependency packages can be extracted.
正常提取到公共模块和依赖包的注释

Current Behavior(当前结果)

The project uses the ruoyi framework. Without changing any code or configuration, I simply upgraded from version 2.4.8 to 2.4.9. After the upgrade, comments from the public module and dependency packages could no longer be extracted.
Observing the log output, there was a change in the way "Smart-doc has loaded the source code path" was logged, and the printed source code paths only included direct dependencies, not indirect ones.
项目使用ruoyi框架。没有改动任何代码和配置。只是把版本从2.4.8升级到2.4.9。公共模块和依赖包中的注释就不能提取了。
观察日志输出，Smart-doc has loaded the source code path这段日志的输出方式发生了改变，并且打印的 source code path只有直接依赖路径，没有间接依赖路径。

Possible Solution(bug解决建议)

After examining the plugin source code, it appears thatAfter examining the plugin source code, it appears that upgrade have altered the logic, it appears that changes made in the code upgrade have altered the logic, preventing the loading of comments from indirectly dependent source code.
观察了插件源代码，应该是代码升级，修改了逻辑，导致不能加载间接依赖的源码注释。

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

Context(Bug影响描述)

Your Environment(您的使用环境)

• smart-doc version:
• plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin): 2.4.9
• build tool version(maven or gradle): maven

Expected Behavior(您期望的结果)

Generate the document based on the corresponding field attributes.
根据对应字段属性生成文档。

Current Behavior(当前结果)

The document generated from the field attributes does not match.
字段属性生成的文档不匹配。

Possible Solution(bug解决建议)

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

Context(Bug影响描述)

The return value JsonResult<Page> has the Page implementing the IPage interface.
The Page object's orders field, protected List orders = new ArrayList<>();, has resulted in the document fields becoming the attributes of the GroupVo class.
返回值JsonResult<Page>的Page实现IPage接口。
Page对象的orders字段protected List orders = new ArrayList<>();，生成的文档字段成了GroupVo里面的字段属性。

Your Environment(您的使用环境)

• smart-doc version: 2.4.5
• plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin): smart-doc-maven-plugin2.4.5
• build tool version(maven or gradle): 3.8.4

Expected Behavior(您期望的结果)

Current Behavior(当前结果)

2.5.3后修改的代码错误的移除了com.smartdoc.chain下基于责任链设计模式过滤丢弃不必要依赖的功能。默认添加的很多依赖加载进入是无作用。恢复其作用提升使用体验。

Possible Solution(bug解决建议)

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

Context(Bug影响描述)

Your Environment(您的使用环境)

• smart-doc version:
• plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin):
• build tool version(maven or gradle):

Summary

First of all, thank you very much to the author for providing such a good documentation plugin. This is currently the only slightly flawed part; it's almost perfect. I found that there seems to be an issue with parsing properties of objects that depend on the public package source during my tests, and I haven't been able to identify the cause yet.
首先非常感谢作者能提供这么好的文档插件，这是目前唯一用着有点小缺陷的地方，基本完美了，我在测试中发现对公共包source依赖的对象属性解析有点问题目前没查到原因.

Basic example

There's a pagination object in the common package, and all business pagination parameter objects inherit from this class, but they cannot be parsed. I tried building a local non-snapshot source.jar (without a private repository), but it wasn't generated.
公共包里有个分页对象，所有业务分页参数对象继承此类，但却无法解析，尝试本地打包非快照的source.jar（无私服）没有生成

Motivation

Enhancement suggestions:

1. Enhance the customResponseFields property column override configuration to support ignore: true/false; required: true/false;
2. Add basic capability expansion and support for ignore and required based on 1 in customerRequestFields;

If these cannot be provided, could you kindly provide a way to scan dependent jars? I have already configured specific scanning in includes, and I have read the official documentation, as well as checked the historical issues submitted on Gitee, but the problem remains unresolved.
建议增强：

1. customResponseFields里属性列覆盖配置支持ignore：true/false；required：true/false；
2. customerRequestFields增加1的基础能力扩展和支持ignore和required；

如果不能提供，能否辛苦提供下扫描依赖jar的办法，includes里已经配置指定扫描且官方文档都看过了，并且历史提交issues在gitee都看了，还是解决不了问题。

Summary

I hope there will be an error message when the configFile is not found.

Basic example

Motivation

When the configFile specified in plugin is not found, it directly returns without any prompt or error message. Maven shows 'BUILD SUCCESS' even though the doc cannot be found.
I didn't consider this during the first use and only discovered the typo after comparing the documentation several times; the value of configFile differs from what's under resources.
Adding an error message prompt here would be much more user-friendly. Moreover, deeming 'BUILD SUCCESS' when no configuration file is found and there is also no 'default.json' seems quite unreasonable.
这里未找到plugin里配置的configFile直接返回了,没有提示和报错,maven显示BUILD SUCCESS却找不到doc
第一次使用时没想到这点对比几次文档才发现手误了,configFile的值和resources下不一样
这里加一个错误信息提示会友好很多,而且没有找到配置文件也没有default.json的情况下认为BUILD SUCCESS也不太合理

1. Regarding Java type issues:
   In the documentation, the int type is seen as int32, and the long type is seen as int64.

2. Concerning header issues:
   The document scan did not capture the header parameters, and some interfaces do have header parameters.

1、java 类型问题
int类型在文档看到是int32，long类型看到是int64

2、header问题
文档扫描没有扫描获取header参数，有些接口是有header参数

Expected Behavior(您期望的结果)

In version 2.1.7, it worked fine; the last 1 or 2 columns of the table would not wrap automatically, and the display was OK.
2.1.7版本中是可以的，表格最后1、2列不会自动换行，展示效果ok

Current Behavior(当前结果)

In version 2.1.7 and later (currently viewing the effect in version 2.5.3), the last 1 or 2 columns of the table will wrap, causing the rendered MD table to be disordered.
在2.1.7及之后的版本中(当前效果以2.5.3版本生成)，表格最后1、2列会有换行，导致渲染出来的md表格错乱

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

import lombok.Data;

/**
 * test-vo
 *
 * @author junying 2022/09/15
 */
@Data
public class TestVo {

    /**
     * xxx
     */
    private String field1;

    /**
     * yyy
     */
    private String field2;

}

Context(Bug影响描述)

Your Environment(您的使用环境)

• smart-doc version:
• smart-doc-maven-plugin version: 2.5.3
• build tool version(maven or gradle): maven 3.8.6

I followed the wiki instructions to use the Maven plugin to generate HTML, but it didn't scan for interface content. The relevant information is as follows:
按照wiki说明使用maven插件生成html，但是扫不到接口内容。相关信息如下：
pom：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>com.xxxx.asp.gateway</groupId>
        <artifactId>asp-gateway-parent</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>asp-gateway-api</artifactId>
    <name>asp-gateway-api</name>
    <description>Demo project for xxxx Boot</description>
    <dependencies>
        <dependency>
            <groupId>com.xxxx.boot</groupId>
            <artifactId>xxxx-boot-autoconfigure</artifactId>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jaxrs</artifactId>
        </dependency>
        <dependency>
            <groupId>javax.validation</groupId>
            <artifactId>validation-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-validator</artifactId>
        </dependency>
        <dependency>
            <groupId>com.xxxx.asp.dataprovider</groupId>
            <artifactId>asp-dataprovider-api</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>1.2.1</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>测试</projectName>
                    <includes>
                        <include>com.xxxx.asp.gateway:asp-gateway-api</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

smart-doc.json：

{
    "isStrict": false,
    "allInOne": true,
    "outPath": "./smart-doc",
    "projectName": "smart-doc"
}

interface：

Generated HTML:

Expected Behavior(您期望的结果)

It is possible to edit and push the data dictionary normally.
能够正常编辑并推送数据字典

Current Behavior(当前结果)

The prompt says the enum class cannot be found.
提示枚举类无法找到

Possible Solution(bug解决建议)

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

1. Pseudocode:
   public interface TestCode{
   enum TestEnum{
   OK(0, "成功");
   TestEnum(int code, String msg) {
   this.code=code;
   this.msg=msg;
   }
   }
   }
2. Configuration file
   {
   "title": "Operation successful",
   "enumClassName": "cn.test.constant.TestCode.TestEnum",
   "codeField": "code",
   "descField": "msg"
   }
   3.Use the smart-doc plugin in IDEA to execute the command smart-doc:torna-rest.
   4.The prompt shows java.lang.ClassNotFoundException: cn.test.constant.TestCode.TestEnum.

Context(Bug影响描述)

When defining an enum within an interface and needing to parse the data dictionary.

Your Environment(您的使用环境)

• smart-doc version:
• plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin):
• build tool version(maven or gradle):
  plugin version:2.4.2
  maven:Apache Maven 3.8.4

Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "12.3", arch: "aarch64", family: "mac"

Summary

Current situation: When exporting a Postman file, it reports that serverUrl must include the protocol http(s). Our local protocol is http, and the environment's protocol is https, which is not conducive to configuring multiple environments in Postman.
当前现状：导出postman文件时，报serverUrl必须带协议http(s)，我们本地协议是http,环境上的协议是https，不利于postman配置多环境

Basic example

I have already seen that Postman's import and export support not specifying the protocol (http(s)). I hope the underlying system can be modified to work without specifying the protocol, like this:
已经看过postman的导入导出是支持不指定协议(http(s)）的，希望底层可以修改成不用指定协议，类似：
"serverUrl": "{{communityDomain}}/community"

Motivation

I hope to support configuring the serverUrl in the following form:
"serverUrl": "{{communityDomain}}/community"

Expected Behavior(您期望的结果)

• smart-doc version: 2.7.7

Current Behavior(当前结果)

When using attribute values from classes outside the project or from third-party libraries, such as constant classes, they cannot be generated in the documentation.
使用了一些项目工程外部库或三方库的类的属性值，例如常量类，在文档中无法生成

Possible Solution(bug解决建议)

Whether the various FilterChain built into the plugin can be configured or manually processed.

• 插件内置的各种 FilterChain 是否可以配置或手动处理

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

Dependent on third-party libraries

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-core</artifactId>
    <version>5.8.20</version>
</dependency>

<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-core</artifactId>
    <version>2.7.15</version>
</dependency>

Plugin configuration

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.7.7</version>
    <configuration>
        <configFile>/Users/delei/Desktop/temp/smartdoc/smart-doc.json</configFile>
        <projectName>${project.description}</projectName>
        <includes>
            <!-- dependency -->
            <include>cn.hutool:.*</include>
            <include>net.dreamlu:.*</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--                        <phase>compile</phase>-->
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Using constant class values from third-party libraries in the controller.
在 controller 中使用三方库的常量类值

@RestController
@RequestMapping(value = "/constant")
public class ConstantController {

    /**
     * Constant use case 01
     *
     * @param userId
     */
    @PostMapping(BaseConstant.BASE_PATH + "/tt-" + MicaConstant.MDC_ACCOUNT_ID_KEY)
    public void constant02(String userId) {
    }


    /**
     * Constant use case 02
     *
     * @param userId
     */
    @PostMapping(BaseConstant.BASE_PATH + "/tt-" + StrUtil.NULL)
    public void constant03(String userId) {
    }
}

Context(Bug影响描述)

• Introduced the built-in FilterChain ignored Hutools third-party library, which cannot be resolved in the documentation.
• Introduced the unignored mica third-party library, which can be resolved in the documentation.

下载了：
https://gitee.com/sunyurepository/api-doc-test
无法使用起来，使用的版本与maven服务器上的根本不一致，并且文档写的maven引用都不一致，这开源不严肃，不认真
https://mvnrepository.com/artifact/com.github.shalousun/smart-doc/1.9.8
上的

而文档中的：
com.github.shalousun
smart-doc-maven-plugin
1.2.2

这是两个不同的东西？？？

Expected Behavior(您期望的结果)

Current Behavior(当前结果)

Steps to Reproduce (Bug产生步骤，请尽量提供用例代码)

1. For an object of type Object<T,S>, the generic type S cannot be recognized, but T can be.
   1.Object<T,S>这种类型的对象，无法识别S的泛型类型,T可以识别

Context(Bug影响描述)

Since I'm integrating smarc-doc + torna for interface document management, and there are some special scenarios that require interaction with C++, the request message format is defined by the other party. In this case, I want to use smarc-doc + torna to maintain the interface documents to reduce communication costs. However, because the second parameter in the generics has not been recognized all the time, it leads to an inability to interact with the documents normally.
由于本人是结合smarc-doc + torna用于接口文档管理，有一些特殊的场景需要与C++做交互，请求报文格式由对方定义，此时想通过smart-doc + torna来维护接口文档，降低沟通成本，由于泛型中的第二个参数一直无法识别，导致文档无法正常交互

Your Environment(您的使用环境)

spring boot(2.3.2) + smart-doc-maven-plugin(2.3.9) + torna(docker->tanghc2020/torna:latest)
代码：

com.power.doc.builder.BaseDocBuilderTemplate#errorCodeDictToList，java.lang.Class#forName(java.lang.String)无法加载本身项目中的类