docs: describe openapi dto generation flow (#5484)

Author: tacklequestions

docs/en/contribution/apollo-development-guide.md

@@ -22,6 +22,23 @@ Please refer to the following sections in [distributed-deployment-guide](en/depl
 
 Please refer to [Apollo Configuration Center Design](en/design/apollo-design) for details.
 
+## 1.3 OpenAPI DTO generation
+
+The `apollo-portal` module generates `OpenXxxDTO` classes (for example `OpenAppDTO`) from OpenAPI YAML definitions during the build.
+If you just cloned the repository or see missing DTO classes reported by the IDE, run a Maven compile phase at the repository root or inside the `apollo-portal` module to regenerate them:
+
+```bash
+mvn clean compile -pl apollo-portal -am
+```
+
+Or run the command directly from the `apollo-portal` directory:
+
+```bash
+mvn clean compile
+```
+
+After the command finishes, the `OpenXxxDTO` classes will appear again under `com.ctrip.framework.apollo.openapi.model`.
+
 # II. Local startup
 
 ## 2.1 Apollo Assembly

docs/en/faq/faq.md

@@ -56,3 +56,18 @@ Here's a quick summary.
 Since we are not experienced users of `Disconf`, we can't give a subjective evaluation.
 However, an enthusiastic user in the Apollo support group [@Krast](https://github.com/krast) made an [Open Source Configuration Center Comparison Matrix](https://github.com/apolloconfig/apollo/files/983064/default.pdf), which can be consulted.
 
+## 11. I get "OpenAppDTO" or other `OpenXxxDTO` classes not found after pulling the latest code, what should I do?
+The `apollo-portal` module generates the `OpenXxxDTO` classes from OpenAPI YAML definitions at build time.
+Run a Maven compile phase to trigger the code generation:
+
+```bash
+mvn clean compile -pl apollo-portal -am
+```
+
+You can also execute the command inside the `apollo-portal` module:
+
+```bash
+mvn clean compile
+```
+
+After it finishes, the OpenAPI DTOs will be regenerated under `com.ctrip.framework.apollo.openapi.model`.

docs/zh/contribution/apollo-development-guide.md

@@ -18,6 +18,23 @@ Apollo本地开发需要以下组件：
 ## 1.2 Apollo总体设计
 具体请参考[Apollo配置中心设计](zh/design/apollo-design)
 
+## 1.3 OpenAPI 代码生成
+`apollo-portal` 模块通过 OpenAPI 的 YAML 描述文件在编译阶段生成 `OpenXxxDTO` 类（例如 `OpenAppDTO`）。
+首次拉取代码或发现在 IDE 中提示这些 DTO 缺失时，请在仓库根目录或 `apollo-portal` 模块目录执行一次
+Maven 编译流程，以触发本地代码生成：
+
+```bash
+mvn clean compile -pl apollo-portal -am
+```
+
+或者直接在 `apollo-portal` 目录执行：
+
+```bash
+mvn clean compile
+```
+
+命令完成后，`com.ctrip.framework.apollo.openapi.model` 包下的 `OpenXxxDTO` 类会重新生成。
+
 # 二、本地启动
 ## 2.1 Apollo Assembly
 我们在本地开发时，一般会在IDE中启动`apollo-assembly`。

docs/zh/faq/faq.md

@@ -54,4 +54,19 @@ Spring Cloud Config的精妙之处在于它的配置存储于Git，这就天然
 ## 10. Apollo和Disconf相比有什么优点？
 
 由于我们自己并非Disconf的资深用户，所以无法主观地给出评价。
-不过之前Apollo技术支持群中的热心网友[@Krast](https://github.com/krast)做了一个[开源配置中心对比矩阵](https://github.com/apolloconfig/apollo/files/983064/default.pdf)，可以参考一下。
+不过之前Apollo技术支持群中的热心网友[@Krast](https://github.com/krast)做了一个[开源配置中心对比矩阵](https://github.com/apolloconfig/apollo/files/983064/default.pdf)，可以参考一下。
+
+## 11. 拉取最新代码后提示找不到 OpenAppDTO 等 `OpenXxxDTO` 类怎么办？
+`apollo-portal` 模块通过 OpenAPI 的 YAML 描述文件在编译阶段生成 `OpenXxxDTO` 类。如果在本地开发时发现这类 DTO 消失或编译报错，请先执行一次 Maven 编译流程触发代码生成：
+
+```bash
+mvn clean compile -pl apollo-portal -am
+```
+
+也可以进入 `apollo-portal` 模块目录直接执行：
+
+```bash
+mvn clean compile
+```
+
+命令完成后，OpenAPI 相关的 DTO 会在 `com.ctrip.framework.apollo.openapi.model` 包下重新生成。