Merge pull request #148 from linwumingshi/docs/typo

docs: update documentation for smart-doc
smart-doc-group · Dec 22, 2024 · 20ac3ac · 20ac3ac
2 parents edf5fea + 7e22516
commit 20ac3ac
Show file tree

Hide file tree

Showing 15 changed files with 108 additions and 93 deletions.
diff --git a/docs/en/guide/advanced/advancedFeatures.md b/docs/en/guide/advanced/advancedFeatures.md
@@ -1,6 +1,6 @@
 # Advanced features
 
-## Public request header
+## Public request header <Badge type="tip" text="^2.2.2" />
 
 **requestHeaders**
 
@@ -83,8 +83,8 @@ public CommonResult<Void> configQueryParamPost(String configQueryParam) {
      return CommonResult.ok();
 }
 ```
-## Static constant replacement
-**Starting from `2.4.2` version, this configuration does not need to be added manually, `smart-doc` can automatically recognize the use of static constants. **
+## ~~Static constant replacement~~
+**Starting from `2.4.2` version, this configuration does not need to be added manually, `smart-doc` can automatically recognize the use of static constants.**
 
 During the development of the `Java Web` interface, some users will use static scenes in the `path` of the `Controller`. Therefore, we also hope that `smart-doc` can parse static constants to obtain the real values.
 Let’s look at an example:
@@ -224,15 +224,15 @@ For example, there is an order status enumeration dictionary in the code.
 
 public enum OrderEnum {
 
-    WAIT_PAY("0", "已支付"),
+    WAIT_PAY("0", "wait to pay"),
 
-    PAID("1", "已支付"),
+    PAID("1", "paid"),
 
-    EXPIRED("2","已经失效");
+    EXPIRED("2","expired");
 
-    private String code;
+    private final String code;
 
-    private String desc;
+    private final String desc;
 
     OrderEnum(String code, String desc) {
         this.code = code;

diff --git a/docs/en/guide/advanced/config.md b/docs/en/guide/advanced/config.md
@@ -64,7 +64,7 @@
 |                                `showValidation`                                | `3.0.3` |    ❌     | `Boolean`      |       `true`        | `showValidation` is used to control whether `smart-doc` extracts the JSR validation information of fields for display in the documentation.                                                                                                                                                                                                                                                                                                                                                                                  |
 |                                    `jmeter`                                    | `3.0.4` |    ❌     | `Object`       |                     | Custom Configurations for JMeter Performance Test Script Generation                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 |                            `addDefaultHttpStatuses`                            | `3.0.5` |    ❌     | `Boolean`      |       `false`       | When generating documentation, consider whether to include the default HTTP status codes from frameworks such as Spring MVC's default `500` and `404` errors. Currently, only the generation of `OpenAPI` documentation supports this feature.                                                                                                                                                                                                                                                                               |
-|                                 `enumConvertor`                                | `3.1.0` |    ❌     | `Boolean`      |       `false`       | In the header/path/query request mode, whether to enable the enumeration converter, The default value is false. <br/>If true, the enumeration value is parsed as an enumeration example value. <br/>If false, take the enumeration name as the enumeration example value                                                                                                                                                                                                                                                               |
+|                                `enumConvertor`                                 | `3.1.0` |    ❌     | `Boolean`      |       `false`       | In the header/path/query request mode, whether to enable the enumeration converter, The default value is false. <br/>If true, the enumeration value is parsed as an enumeration example value. <br/>If false, take the enumeration name as the enumeration example value                                                                                                                                                                                                                                                     |
 
 ```json
 {

diff --git a/docs/en/guide/advanced/debug.md b/docs/en/guide/advanced/debug.md
@@ -1,6 +1,6 @@
 # Interface UI integration
 
-## `smart-doc` debug page
+## `smart-doc` debug page <Badge type="tip" text="^2.0.0" />
 
 Starting from `smart-doc 2.0.0` version, in `allInOne` mode of `html`. You can add the configuration of `"createDebugPage": true`. `smart-doc` will
 Create a `debug.html` page. When letting `smart-doc` generate documents, put them directly under `static/doc/`.
@@ -73,7 +73,7 @@ Dependency, so if you want to debug the interface, you can only generate html do
 Of course, the smart-doc debugging page can only upload one file for file upload, which is weaker than the Swagger UI. But smart-doc also has advantages over Swagger UI.
 For example: the document display is clearer; support for downloading test files
 
-## `Postman` import debugging
+## `Postman` import debugging <Badge type="tip" text="^1.7.8" />
 Starting from `smart-doc 1.7.8` version, `smart-doc` supports generating `json` files of `Postman`,
 You can use `smart-doc` to generate `Postman` `json` files for the entire project or all interfaces of a microservice.
 Then do the test by importing this `json` file into `Collections` of `Postman`. Export `json`.

diff --git a/docs/en/guide/community/contributing.md b/docs/en/guide/community/contributing.md
@@ -13,6 +13,11 @@ If you would like to contribute to `smart-doc`, you can follow these steps:
 
 4. After completing your modifications, push the commits and submit a Pull Request to the main `smart-doc` repository. Please refer to the [Pull Request](pull-request-process) process to submit your merge request.
 
+::: tip  
+The code should adhere to the `smart-doc` coding style (using the Spring code style). Please use the command `mvn spring-javaformat:apply` to format the code.  
+It is recommended to download the [Spring Java Format](https://github.com/spring-io/spring-javaformat) plugin.  
+:::
+
 5. Wait for the community Committers to review and merge your Pull Request.
 
 6. If the merge is successful, congratulations, you have made a successful contribution!

diff --git a/docs/en/guide/faq/faq.md b/docs/en/guide/faq/faq.md
@@ -213,7 +213,7 @@ You can refer to the following documents to learn alternative configurations:
 
 [Spring boot uses Maven Profile and Spring Profile for multi-environment configuration and packaging](https://cloud.tencent.com/developer/article/1769239)
 
-## plug-in
+## Plug-in
 
 ### The project cannot load the smart-doc plug-in
 The error message is as follows:

diff --git a/docs/en/guide/getting-started.md b/docs/en/guide/getting-started.md
@@ -49,7 +49,7 @@ Configure the `Maven plug-in` in the `pom.xml` file of the module where the proj
 </plugin>
 
 ```
-> `includes` needs to be adjusted to configure `artifactId:groupId` for the packages that the project module depends on, and supports regular `artifactId:*`
+> `includes` needs to be adjusted to configure `groupId:artifactId` for the packages that the project module depends on, and supports regular `artifactId:*`
 
 
 If the project depends on other internal public modules and second-party packages, the dependent packages need to be configured with source code packaging.

diff --git a/docs/en/guide/guide.md b/docs/en/guide/guide.md
@@ -270,7 +270,9 @@ public void download(HttpServletResponse response) throws IOException {
 }
 ```
 
-Starting from smart-doc 2.0.2, the file name will automatically be read from the download response header `Content-Disposition: attachment; filename=xx`, so there is no need to set `response.setHeader("filename", urlEncode(fileName));` in the response header.
+:::tip  TIPS <Badge type="tip" text="^2.0.2" />
+Starting from `smart-doc` 2.0.2, the file name will automatically be read from the download response header `Content-Disposition: attachment; filename=xx`, so there is no need to set `response.setHeader("filename", urlEncode(fileName));` in the response header.
+:::
 
 If the response type is one of the following:
 - `org.springframework.core.io.Resource`

diff --git a/docs/en/guide/plugins/maven.md b/docs/en/guide/plugins/maven.md
@@ -1,4 +1,4 @@
-# Maven
+# Maven  <Badge type="tip" text="^1.7.9" />
 Starting from `smart-doc 1.7.9`, the `Maven` plug-in is officially provided, and documents can be generated directly by running the plug-in in the project.
 
 ## Environmental requirements
@@ -62,7 +62,7 @@ Specify the project name. It is recommended to use dynamic parameters, such as `
 Starting from `2.3.4`, if the projectName is not set in `smart-doc.json` or here, the plug-in is automatically set to the projectName in the pom.
 
 #### excludes & includes
-
+ excludes & includes are used to control the loading of source code.
 ##### Loading source code mechanism
 smart-doc will automatically analyze the dependency tree and load all dependent source codes, but this will cause two problems:
 1. Loading unnecessary source code affects document construction efficiency

diff --git a/docs/zh/guide/advanced/advancedFeatures.md b/docs/zh/guide/advanced/advancedFeatures.md
@@ -1,6 +1,6 @@
 # 高级特性
 
-## 公共请求头
+## 公共请求头 <Badge type="tip" text="^2.2.2" />
 
 **requestHeaders**
 
@@ -86,8 +86,10 @@ public CommonResult<Void> configQueryParamPost(String configQueryParam) {
 }
 ```
 
-## ~~静态常量替换~~
-**`2.4.2`版本开始，这个配置无需再手动添加，`smart-doc`可以自动识别静态常量的使用。**
+## ~~静态常量替换~~ <Badge type="danger" text="^2.4.2" />
+:::tip
+**`@sice 2.4.2`版本开始，这个配置无需再手动添加，`smart-doc`可以自动识别静态常量的使用。**
+:::
 
 在`Java Web`接口开发的过程中，有些用户会在`Controller`的路径中使用静态常量。因此，
 他们也希望`smart-doc`能够解析这些静态常量并获取到真实的值。下面来看一个例子：

diff --git a/docs/zh/guide/advanced/debug.md b/docs/zh/guide/advanced/debug.md
@@ -1,6 +1,6 @@
 # 接口UI集成
 
-## `smart-doc`调试页面
+## `smart-doc`调试页面 <Badge type="tip" text="^2.0.0" />
 
 从`smart-doc 2.0.0`版本开始，在`html`的`allInOne`的模式下。可以添加`"createDebugPage": true`的配置。`smart-doc`会
 创建一个`debug.html`的页面。 在让生成`smart-doc`生成文档时直接放入到`static/doc/`下，
@@ -73,7 +73,7 @@ public class WebConfig implements WebMvcConfigurer {
 当然smart-doc的调试页面对于文件上传你只能传一个文件，这点相比Swagger UI要弱。但是smart-doc也有比Swagger UI强的地方，
 例如：文档展示更清晰明了；支持测试文件下载
 
-## `Postman` 导入调试
+## `Postman` 导入调试   <Badge type="tip" text="^1.7.8" />
 从`smart-doc 1.7.8`版本开始，`smart-doc`支持生成`Postman`的`json`文件，
 你可以使用`smart-doc`生成整个项目的或者某个微服务所有接口的`Postman`的`json`文件，
 然后通过将这个`json`文件导入`Postman`的`Collections`做测试。导出`json`.
@@ -106,6 +106,7 @@ public class WebConfig implements WebMvcConfigurer {
 </dependency>
 ```
 `smart-doc`支持的`OpenAPI`规范版本比较高，因此需要集成`1.5.0`或者是更高的版本。
+
 ### 配置Swagger UI
 在`application`配置文件中添加如下配置
 ```