tip

In the use of frameworks, it's inevitable that exceptions will occur for various reasons. We do not rule out defects in the framework itself (typically less than 0.1%) as a cause; however, the currently released features have all undergone stability testing, coverage by test cases, and validation in production environments by a large number of users. More often than not, issues arise from dependency incompatibilities or users deviating from the documented usage, improvising, which leads to problems. Such users are usually quite lazy; at the slightest hint of a minor issue, they immediately ask questions in the group or complain about the framework being poor quality. In the end, after we assist them in troubleshooting and resolving the issue, it turns out that they did not follow the documentation but instead acted recklessly. We find ourselves helpless in these situations, as our resources and time for open-source projects are limited. We would like to focus our efforts on collecting genuine bugs and iterating to solve them rather than wasting time on trivial matters.Therefore, we hope that users will read the documentation thoroughly before use. When encountering problems, start by referring to the documentation to see if your question is among the frequently asked ones we've provided. Look at how our demos are written; what versions of actual dependencies like javaParser, fastjson, and springboot are used in the demos. Try keeping your project's dependency versions consistent with those in the demos to rule out dependency-related causes. If the problem persists, set breakpoints to investigate the cause and analyze the source code. After going through these steps, if the issue still remains unresolved, you can then ask in the troubleshooting group. This is a basic professional courtesy for coders, and it significantly helps improve your technical skills. If you throw problems over your shoulder every time, over time, your ability to independently solve and analyze problems will deteriorate. If someday you use an open-source product and happen to encounter an issue with no one around to troubleshoot, what will you do then?

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

Given that there's code within the framework to obtain the Maven local repository path, lacking this environment variable can prevent the framework from automatically generating API documentation. Below are two ways to resolve this:

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

Method 1: Add the Maven installation directory variable to the IDEA editor and then start the project

Method 2: Directly configure the environment variable

2.1 Windows users

My Computer -> Advanced System Settings -> Environment Variables -> System Variables -> New -> Variable Name: M2_HOME, Variable Value: Your Maven installation directory, for example: C:\Program Files\maven\apache-maven-3.6.3

2.2 macOS users

On macOS, adding a system environment variable can be achieved by editing shell configuration files（such as ~/.bash_profile󠁪, ~/.zshrc󠁪, ~/.bashrc󠁪, etc.). Below are detailed steps:

2.2.1Determining the Used Shell

macOS defaults to using zsh󠁪, but if you're using another shell (such as bash󠁪), the steps will differ slightly. You can confirm your current shell with the following command:

echo $SHELL

2.2.2 Editing the Shell Configuration File

Edit the appropriate configuration file based on the shell you use:

• For zsh（the default shell on macOS Catalina and newer）：

  nano ~/.zshrc
  

• For bash（on macOS Mojave and older versions）：

  nano ~/.bash_profile
  

2.2.3 Adding Environment Variables

In the opened configuration file, add the following lines to set the M2_HOME󠁪 environment variable (replace /path/to/maven󠁪 with your actual Maven installation path):

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

2.2.4 Saving and Activating Changes

Save the file and activate the changes:

• For the nano editor, press: Ctrl+X , then Y󠁪, and finally Enter󠁪 to save and exit.

• Run the following command to activate the new configuration:

  source ~/.zshrc  # if used zsh
  

  or

  source ~/.bash_profile  # if used bash
  

2.2.5 Verifying the Environment Variable

Verify whether the environment variable has been correctly set with the following command:

echo $M2_HOME

You should see the path to your Maven installation.

2.2.6 Example

Assuming the Maven installation path is /usr/local/Cellar/maven/3.8.1, you can add the following content to ~/.zshrc or ~/.bash_profile：

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

2.Cross-Origin Issues

When using the generated API documentation for online debugging and testing, if you find that all interface requests are Failed, it might be a good idea to enter developer mode in your browser, click on XHR, and find the response information for the requested interface. If the status is 403, then it's likely a cross-origin issue. The generated API documentation is an independent static page, separate from the backend service, so cross-origin requests are inevitable. Therefore, I've included automatic cross-origin support in the doc-apis starter module. However, under certain circumstances, cross-origin issues can still occur, such as in non-SpringBoot projects or when your project has its own cross-origin configurations that conflict with those automatically assembled by the doc-apis framework. This may lead to failures, but there's no need to panic. Cross-origin issues are actually quite easy to resolve. Below, I've compiled several cross-origin solutions for your reference:

2.1 Directly Set the Browser to Allow Cross-Origin (Recommended)

• In the address bar of Google Chrome, visit chrome://flags/#block-insecure-private-network-requests󠁪
• Set the 'Block insecure private network requests' option to 'Disabled'
• Close Google Chrome and reopen the API documentation page, then make the request again to solve the issue.

This method is straightforward and suitable for allowing cross-origin debugging on your local machine. After all, it's a development environment where security concerns don't apply and won't affect the production environment. You can search for methods to allow cross-origin settings in other browsers yourself.

2.2 Configure Backend Service to Allow Cross-Origin Interfaces (Not Recommended)

In the code of your project, find the configuration class that implements the WebMvcConfigurer interface, override the addCorsMappings method, and add the interfaces you wish to debug, allowing them to be accessed cross-origin. This method invades the codebase and requires differentiation between environments; otherwise, it could easily impact the production environment. Hence, it's not recommended.

2.3 Use Nginx

Forward the well-generated API documentation through Nginx. Using Nginx configuration, forward requests to the backend service and include cross-origin permission configurations. This method isn't recommended either, as it's too cumbersome to use.

3.Response Bodies Packed into JAR via Introduction, for Example, PageInfo in the PageHelper Plugin

Once a class is packed into a JAR, it exists as bytecode (.class files), which do not contain annotation information. This is fatal for a framework that generates API documentation based on code annotations. This has been an unresolved issue for JapiDoc, but it has been addressed in doc-apis. Although this situation is a low-probability event, we've provided a SPI-like extension mechanism for users to fix it with one click. The framework now natively supports PageInfo from the PageHelper plugin and EsPageInfo from Easy-Es. If your project includes other response bodies packed into a JAR, you can create an object of this return type at the root directory of your project, add annotations to the fields within the object, and upon startup, the framework will generate documentation based on the proxy object you've created.