温馨提示

在框架使用中,难免会因为各种原因导致异常,我们不排除框架本身有缺陷(通常小于0.1%)导致,但目前发布的功能中,都是稳定且有测试用例覆盖及大量用户生产环境验证过的,更多的时候是依赖不兼容或用户没有按文档使用,自由发挥,导致出现一些问题,这类用户通常还比较懒,一碰到鸡毛大点问题马上来群里问,或是抱怨框架垃圾,然后我们协助排查解决最后发现是xx地方没有按文档使用,而是胡乱搞,我们也很无奈,毕竟做开源,精力和时间也比较有限,我们想把时间花在刀刃上,比如收集真正的bug,去迭代解决,而不是把时间浪费在这些无谓的地方. 所以我们还是希望用户能在使用前多读文档,遇到问题不妨先从文档下手,看看我们提供的高频问答中是否有您想问的问题,看看我们提供的DEMO是怎么写的?DEMO中实际依赖的javaParser,fastjson,springboot版本是多少,不妨先把你项目中的依赖版本与demo中保持一致,排除依赖原因. 如仍未解决可以打断点找找原因,看看源码分析分析,经历了这些步骤,如果仍然解决不了,可以再来答疑群里问,这是一个码农基本的素养,而且对提升自身技术水平有很大帮助,如果碰到问题就抛出去,久而久之,自我独立解决和分析问题的能力会越来越差,长此以往,若有一天用了某款开源产品,碰到问题恰好没人答疑,又当何去何从?

1.报错 java.lang.RuntimeException: M2_HOME environment variable is not set

由于框架内部有获取maven本地仓库地址的代码,缺少此环境变量会导致框架无法自动生成接口文档,可通过下面这两种方式来解决:

String mavenHomeDir = System.getenv("M2_HOME");

方式1.将变量Maven安装目录添加至IDEA编辑器中,再启动项目

方式2.直接配置环境变量

2.1 Windows用户

我的电脑->高级系统设置->环境变量->系统变量->新建-> 变量名:M2_HOME,变量值:你的Maven安装目录,例如:C:\Program Files\maven\apache-maven-3.6.3

2.2 macOS用户

在macOS上新增系统环境变量，可以通过编辑shell配置文件（如~/.bash_profile, ~/.zshrc, ~/.bashrc等）来实现。以下是详细步骤：

2.2.1 确定所使用的shell

macOS默认使用的是zsh，但如果你使用的是其他shell（如bash），步骤会略有不同。你可以通过以下命令确认当前使用的shell：

echo $SHELL

2.2.2 编辑shell配置文件

根据你使用的shell，编辑相应的配置文件：

• 对于zsh（默认shell，macOS Catalina及更新版本）：

  nano ~/.zshrc
  

• 对于bash（macOS Mojave及更早版本）：

  nano ~/.bash_profile
  

2.2.3 添加环境变量

在打开的配置文件中，添加以下行来设置M2_HOME环境变量（将/path/to/maven替换为实际的Maven安装路径）：

export M2_HOME=/path/to/maven
export PATH=$M2_HOME/bin:$PATH

2.2.4 保存并使更改生效

保存文件并使更改生效：

• 对于nano编辑器，按Ctrl+X，然后按Y，最后按Enter保存并退出。

• 运行以下命令使新配置生效：

  source ~/.zshrc  # 如果使用的是zsh
  

  或

  source ~/.bash_profile  # 如果使用的是bash
  

2.2.5 验证环境变量

通过以下命令验证环境变量是否已正确设置：

echo $M2_HOME

你应该看到Maven的安装路径。

2.2.6示例

假设Maven安装路径为/usr/local/Cellar/maven/3.8.1，你可以在~/.zshrc或~/.bash_profile中添加如下内容：

export M2_HOME=/usr/local/Cellar/maven/3.8.1
export PATH=$M2_HOME/bin:$PATH

2.跨域问题

当您使用生成的接口文档进行在线debug调试时,发现所有接口请求都是Failed,此时不妨进入浏览器的开发者模式,点击XHR并找到请求接口的响应信息,如果是403,那就是跨域了, 因为生成的接口文档为独立的静态页面,与后端服务并不在一起,所以请求一定会跨域,因此我在doc-apis的starter模块中做了自动跨域的支持,但个别场景下仍会出现跨域问题, 例如非springboot项目,或是项目本身配置了针对项目自身的一些跨域,与doc-apis框架中自动装配的跨域冲突了,此时就可能会导致失效,但也不用慌,跨域其实很好解决,下面整理 了几种跨域方案,供大家参考:

2.1直接设置浏览器,使其允许跨域(推荐)

• 谷歌浏览器地址栏访问 chrome://flags/#block-insecure-private-network-requests
• 将Block insecure private network requests 选项设置为 Disabled
• 关闭谷歌浏览器,并重新打开接口文档页面,再次发起请求即可解决

此方法简单粗暴,并且在自己本地机器进行允许跨域调试,没什么毛病,毕竟是开发环境,不涉及安全问题,不影响生产环境,其它浏览器可自行搜索允许跨域设置方法.

2.2 后端服务配置允许跨域的接口(不推荐)

在您工程的代码中找到实现了接口WebMvcConfigurer的相关配置类,覆写方法addCorsMappings中添加上您期望调试的接口,使其允许跨域访问,此方法会侵入代码, 并且需要区分环境,否则很容易影响到生产环境,因此并不推荐.

2.3 使用nginx

把框架生成好的接口文档通过nginx进行转发,通过Nginx配置将请求转发到后端服务,并在Nginx配置中加入允许跨域的配置,此方法也不推荐,使用起来太麻烦了.

3.返回体被打包进jar,通过引入的情况,例如PageHelper插件中的PageInfo

当一个类被打包进jar以后,是以字节码.class文件存在的,.class文件中并没有注释信息,这对一个以代码注释为基准生成接口文档的框架来说是致命的,这也是JapiDoc 一直未能解决的问题,不过此问题在doc-apis中得到了解决,虽然这种情况属于小概率事件,但我们还是提供了类似于spi的拓展机制,方便用户一键解决, 目前框架已经内置兼容了PageHelper插件中的PageInfo 和Easy-Es中的EsPageInfo,如果您的项目中有其它类似被打包进jar的返回体时, 可以在您的项目根目录下创建该返回体的对象,针对对象中的字段加上注释,启动后框架则以您创建的该代理对象为基准进行生成.