diff --git a/docs/_images/002115_04d0246d_144669.png b/docs/_images/002115_04d0246d_144669.png deleted file mode 100644 index 6d18cb4..0000000 Binary files a/docs/_images/002115_04d0246d_144669.png and /dev/null differ diff --git a/docs/_images/004113_df83ee8d_144669.png b/docs/_images/004113_df83ee8d_144669.png deleted file mode 100644 index fd82d58..0000000 Binary files a/docs/_images/004113_df83ee8d_144669.png and /dev/null differ diff --git a/docs/_images/004808_63ad37db_144669.png b/docs/_images/004808_63ad37db_144669.png deleted file mode 100644 index fe7a52a..0000000 Binary files a/docs/_images/004808_63ad37db_144669.png and /dev/null differ diff --git a/docs/_images/095300_24a7f126_144669.png b/docs/_images/095300_24a7f126_144669.png deleted file mode 100644 index a730d04..0000000 Binary files a/docs/_images/095300_24a7f126_144669.png and /dev/null differ diff --git a/docs/_images/141540_aed7de0b_144669.png b/docs/_images/141540_aed7de0b_144669.png deleted file mode 100644 index bed475f..0000000 Binary files a/docs/_images/141540_aed7de0b_144669.png and /dev/null differ diff --git a/docs/_images/232807_f88b94b2_144669.png b/docs/_images/232807_f88b94b2_144669.png deleted file mode 100644 index 2208122..0000000 Binary files a/docs/_images/232807_f88b94b2_144669.png and /dev/null differ diff --git a/docs/_images/debug-console.png b/docs/_images/debug-console.png index 3cc1044..4a154da 100644 Binary files a/docs/_images/debug-console.png and b/docs/_images/debug-console.png differ diff --git a/docs/_images/gradle-debub.png b/docs/_images/gradle-debub.png new file mode 100644 index 0000000..b731c2c Binary files /dev/null and b/docs/_images/gradle-debub.png differ diff --git a/docs/_images/gradle-run-debug.png b/docs/_images/gradle-run-debug.png new file mode 100644 index 0000000..520161c Binary files /dev/null and b/docs/_images/gradle-run-debug.png differ diff --git a/docs/_images/maven-plugin-debug.png b/docs/_images/maven-plugin-debug.png new file mode 100644 index 0000000..a7bd4f9 Binary files /dev/null and b/docs/_images/maven-plugin-debug.png differ diff --git a/docs/_images/mock.png b/docs/_images/mock.png index 63eb696..7050492 100644 Binary files a/docs/_images/mock.png and b/docs/_images/mock.png differ diff --git a/docs/_images/postman-add-env.png b/docs/_images/postman-add-env.png new file mode 100644 index 0000000..23283fc Binary files /dev/null and b/docs/_images/postman-add-env.png differ diff --git a/docs/_images/postman-import.png b/docs/_images/postman-import.png new file mode 100644 index 0000000..87f9a9e Binary files /dev/null and b/docs/_images/postman-import.png differ diff --git a/docs/_images/set-gradle-debug-name.png b/docs/_images/set-gradle-debug-name.png new file mode 100644 index 0000000..b9051b8 Binary files /dev/null and b/docs/_images/set-gradle-debug-name.png differ diff --git a/docs/advanced/debug.md b/docs/advanced/debug.md index 5ea22db..172a02d 100644 --- a/docs/advanced/debug.md +++ b/docs/advanced/debug.md @@ -80,11 +80,11 @@ Then do the test by importing this `json` file into `Collections` of `Postman`. The effect of importing `json` to `Postma`n is as follows: -![Enter picture description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/095300_24a7f126_144669.png "postman.png") +![Enter picture description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/postman-import.png "postman.png") ### Set environment variables in postman -![Enter picture description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/141540_aed7de0b_144669.png "postman_set_env.png") +![Enter picture description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/postman-add-env.png "postman_set_env.png") **Note:** Don’t forget to set a name for the environment in `Add Environment` (for example: local development and testing), otherwise the save will not be successful according to the picture above. > The Json file automatically generated by smart-doc will be thoughtfully filled in with comments in Postman. If you write the mock value yourself, it will also be carried in. diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 7631422..30c844f 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -37,9 +37,9 @@ When contributing to `smart-doc`, please pay attention to the following: ## Code Review All code must go through a `Committer` review. Here are some principles we recommend: -- Readability: All submissions should follow good coding and documentation standards. -- Elegance: The code should be concise, highly reusable, and well-designed. -- Testing: Add unit tests for ordinary methods in `smart-doc`, and for user interface code, please add test cases and complete submission testing validation in [smart-doc-demo](https://github.com/smart-doc-group/smart-doc-demo). +- **Readability:** All submissions should follow good coding and documentation standards. +- **Elegance:** The code should be concise, highly reusable, and well-designed. +- **Testing:** Add unit tests for ordinary methods in `smart-doc`, and for user interface code, please add test cases and complete submission testing validation in [smart-doc-demo](https://github.com/smart-doc-group/smart-doc-demo). ## Case Sharing We very much welcome you to share any usage cases related to `smart-doc`. We encourage everyone to submit articles and share their `smart-doc` usage cases. diff --git a/docs/diy/advancedFeatures.md b/docs/diy/advancedFeatures.md index 96170c4..b206e3e 100644 --- a/docs/diy/advancedFeatures.md +++ b/docs/diy/advancedFeatures.md @@ -381,11 +381,11 @@ PostmanJsonBuilder.buildPostmanCollection(config); example: -![输入图片说明](../../_images/095300_24a7f126_144669.png "postman.png") +![输入图片说明](../../_images/postman-import.png "postman.png") ### postman中设置环境变量 -![输入图片说明](../../_images/141540_aed7de0b_144669.png "postman_set_env.png") +![输入图片说明](../../_images/postman-add-env.png "postman_set_env.png") ** Note: ** Do not forget to set the name of the environment in Add Environment (for example: local development test), otherwise the environment cannot be saved successfully according to the above figure. diff --git a/docs/integrated/dubbo.md b/docs/integrated/dubbo.md index 998bc31..e32a517 100644 --- a/docs/integrated/dubbo.md +++ b/docs/integrated/dubbo.md @@ -183,6 +183,6 @@ public class UserServiceImpl implements UserService { ``` ## Generate operations Run the plug-in's document generation command directly through the `mvc` command or directly click the plug-in's visual command in `IDEA`. -![maven-smart-doc](https://img-blog.csdnimg.cn/20200705230512435.png) +![maven-smart-doc](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/20200705230512435.png "1.png") Run `rpc-html` etc. to generate `Dubbo RPC` document \ No newline at end of file diff --git a/docs/plugins/gradle.md b/docs/plugins/gradle.md index b23288a..552a769 100644 --- a/docs/plugins/gradle.md +++ b/docs/plugins/gradle.md @@ -98,27 +98,31 @@ For example, create `/src/main/resources/smart-doc.json` in the project. The con #### Generated document ##### Use Gradle command ```bash -//generate html +// Generate documentation into HTML gradle smartDocRestHtml -//Generate markdown +// Generate markdown gradle smartDocRestMarkdown -//Generate adoc +// Generate adoc gradle smartDocRestAdoc -//Generate postmanjson data +// Generate Postman JSON data gradle smartDocPostman -//Generate Open Api 3.0+ standard json document, since smart-doc-gradle-plugin 1.1.4 +// Generate Open API 3.0 + specification JSON documentation, since smart-doc-gradle-plugin 1.1.4 gradle smartDocOpenApi -//Generate rest interface documents and push them to Torna platform, @since 2.0.9 +// Generate REST API documentation and push to Torna platform, @since 2.0.9 gradle tornaRest +// Generate JMeter performance test scripts, since 3.0.0 +gradle smartDocJmeter +// Generate documentation output to Word, since 3.0.0 +gradle word -// Apache Dubbo Rpc +// Apache Dubbo RPC generation // Generate html gradle smartDocRpcHtml // Generate markdown gradle smartDocRpcMarkdown // Generate adoc gradle smartDocRpcAdoc -// push torna rpc +// Push RPC interfaces to torna gradle tornaRpc ``` ##### Use IDEA @@ -147,7 +151,7 @@ dependencies { } ``` Find the `smart-doc` source code and put a breakpoint. The operation is as follows: -![Break point example](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/002115_04d0246d_144669.png "debug1.png") +![Break point example](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/gradle-debug.png "debug1.png") ### Command line terminal to set debug mode Debugging the `Gradle` plugin is not as simple as debugging `JAVA` programs and `Maven` plugins. You can debug directly by clicking `debug` on `IDEA` to start related operations. It is necessary to set the debugging mode on the command line. The operation is as follows: @@ -171,7 +175,7 @@ gradle wrapper Click **Edit Configurations** ![Enter picture description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004033_cd63df34_144669.png "remote1.png") Click on the "+" sign on the left and click "Remote" -![Add remote](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004113_df83ee8d_144669.png "remote2.png") +![Add remote](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/set-gradle-debug-name.png "remote2.png") ### Perform debugging After completing the above operation, you can use `debug` to debug the plug-in and `smart-doc`, and then check the execution status of `smart-doc`. The operation is as shown below -![Execute debugging](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004808_63ad37db_144669.png "debug3.png") \ No newline at end of file +![Execute debugging](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/gradle-run-debug.png "debug3.png") \ No newline at end of file diff --git a/docs/plugins/maven.md b/docs/plugins/maven.md index ee9853f..1f61396 100644 --- a/docs/plugins/maven.md +++ b/docs/plugins/maven.md @@ -49,12 +49,12 @@ The usage reference is as follows: ``` ### configuration #### configFile -Specifies the configuration file used to generate documentation. Please use ./ at the beginning of the relative path, eg: `./src/main/resources/smart-doc.json` +Specifies the configuration file used to generate documentation. Please use `./` at the beginning of the relative path, eg: `./src/main/resources/smart-doc.json` #### projectName -Specify the project name. It is recommended to use dynamic parameters, such as ${project.description}. +Specify the project name. It is recommended to use dynamic parameters, such as `${project.description}`. -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. +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 @@ -86,7 +86,7 @@ Usually the only dependencies we need are a few common third-party libraries, th com.xxx:.* - + ``` @@ -96,15 +96,15 @@ When running the plug-in, if some Class cannot be loaded, exclude the dependenci ```xml - + org.springframework.boot:spring-boot-mongodb - + ``` ##### excludes & includes best practices 1. To use include, load the required source code. If you don’t need other dependencies, you can write the project’s own `groupId:artifactId` -2. After encountering an error, use excludes to exclude the dependencies of the error. + 2. After encountering an error, use `excludes` to `exclude` the dependencies of the error. @@ -129,13 +129,21 @@ In the above `json` configuration example, only `"outPath"` is required. Other c ``` mvn -Dfile.encoding=UTF-8 smart-doc:html +// Generate document output to Markdown mvn -Dfile.encoding=UTF-8 smart-doc:markdown +// Generate document output to Adoc mvn -Dfile.encoding=UTF-8 smart-doc:adoc +// Generate Postman. mvn -Dfile.encoding=UTF-8 smart-doc:postman // build Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5 mvn -Dfile.encoding=UTF-8 smart-doc:openapi -// build to torna +// Generate document and push to torna mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest +// Generate document output to Word. +mvn -Dfile.encoding=UTF-8 smart-doc:word +// Generate Jmeter performance pressure test scripts. +mvn -Dfile.encoding=UTF-8 smart-doc: + // Apache Dubbo RPC // Generate html @@ -194,7 +202,7 @@ Usually the actual debugged code is `smart-doc`. But this process is mainly chec ## Add breakpoint Add breakpoints as shown in the figure -![Enter image description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/232807_f88b94b2_144669.png "maven-debug1.png") +![Enter image description](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/maven-plugin-debug.png "maven-debug1.png") ## Run the build target in Debug mode It is very simple for the `maven` plug-in to run `debug` in `idea`. The operation is as shown below. diff --git a/docs/zh-cn/advanced/debug.md b/docs/zh-cn/advanced/debug.md index bd9de40..7bc8ed8 100644 --- a/docs/zh-cn/advanced/debug.md +++ b/docs/zh-cn/advanced/debug.md @@ -80,11 +80,11 @@ public class WebConfig implements WebMvcConfigurer { 导入`json`到`Postma`n效果如下图: -![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/095300_24a7f126_144669.png "postman.png") +![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/postman-import.png "postman.png") ### postman中设置环境变量 -![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/141540_aed7de0b_144669.png "postman_set_env.png") +![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/postman-add-env.png "postman_set_env.png") **注意:** 在`Add Environment`中不要忘记给环境设置名称(例如:本地开发测试),否则按上图不能保存成功。 > smart-doc自动生成的Json文件会贴心的给在Postman中给填充上注释,如果你自己写了mock值也会携带进入, diff --git a/docs/zh-cn/community/developer.md b/docs/zh-cn/community/developer.md index 9262cfd..58645ea 100644 --- a/docs/zh-cn/community/developer.md +++ b/docs/zh-cn/community/developer.md @@ -2,26 +2,6 @@ # 社区角色 `smart-doc`社区包含`Maintainer`、`Committer`、`Contributor`等角色,每种角色的标准定义如下。 - -# smart-doc开发团队 -感谢所有开发者对社区的贡献!我们会定期将所有贡献者的名字进行展示,当然也可以自己提交`PR`添加。 -> 注:排名不分先后。如有遗漏,请提交 PR 添加。 - -### PMC(项目管理委员会,Project Management Committee) -- Yu Sun([@shalousun](https://github.com/shalousun)) - -### Committer -- Xingzhi Li([@netdied](https://github.com/netdied)) -- Qi Chen([@chenqi146](https://github.com/chenqi146)) -- Bing Li([@abing22333](https://github.com/abing22333)) - - -### Contributor -https://github.com/TongchengOpenSource/smart-doc/graphs/contributors - - ---- - ### Maintainer 对`smart-doc`项目演进和发展做出显著贡献的个人。 @@ -35,7 +15,7 @@ https://github.com/TongchengOpenSource/smart-doc/graphs/contributors - 参与新晋`Committer`或`Maintainer`的提名及投票。 ### Committer -是对`smart-doc`社区某些特定领域做出突出贡献的人 +是对`smart-doc`社区某些特定领域做出突出贡献的人 成为`Committer`的标准: - 能够长时间地并持续性地贡献`Issue`、`PR`代码、测试用例、文档、案例),社区贡献`10`个及以上高质量`PR`; @@ -63,6 +43,30 @@ https://github.com/TongchengOpenSource/smart-doc/graphs/contributors 如果您成为了`Smart-doc Contributor`并且持续地做出贡献,达到了`Committer`的要求,我们将邀请您成为`Smart-doc Committer`. +# smart-doc开发团队 +感谢所有开发者对社区的贡献!我们会定期将所有贡献者的名字进行展示,当然也可以自己提交`PR`添加。 +> 注:排名不分先后。如有遗漏,请提交 PR 添加。 + +### PMC(项目管理委员会,Project Management Committee) +- Yu Sun([@shalousun](https://github.com/shalousun)) + +### Committer +- Xingzhi Li([@netdied](https://github.com/netdied)) +- Qi Chen([@chenqi146](https://github.com/chenqi146)) +- Bing Li([@abing22333](https://github.com/abing22333)) + +#### 相关宣传 +- [第一批Committer晋升公告](https://www.oschina.net/news/282477) + +### Contributor +https://github.com/TongchengOpenSource/smart-doc/graphs/contributors + + + + + + + diff --git a/docs/zh-cn/plugins/gradle.md b/docs/zh-cn/plugins/gradle.md index 7a242bc..bb9c702 100644 --- a/docs/zh-cn/plugins/gradle.md +++ b/docs/zh-cn/plugins/gradle.md @@ -99,7 +99,7 @@ https://gitee.com/smart-doc-team/smart-doc-gradle-plugin-demo #### Generated document ##### Use Gradle command ```bash -//生成html +//生成文档到html中 gradle smartDocRestHtml //生成markdown gradle smartDocRestMarkdown @@ -111,6 +111,11 @@ gradle smartDocPostman gradle smartDocOpenApi //生成rest接口文档并推送到Torna平台,@since 2.0.9 gradle tornaRest +//生成Jmeter性能压测脚本,since 3.0.0 +gradle smartDocJmeter +//生成文档输出到Word,since 3.0.0 +gradle word + // Apache Dubbo Rpc生成 // Generate html @@ -148,7 +153,7 @@ dependencies { } ``` 找到`smart-doc`源码打上断点。操作如下图: -![打断点示例](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/002115_04d0246d_144669.png "debug1.png") +![打断点示例](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/gradle-debug.png "debug1.png") ### 命令行终端设置debug模式 `Gradle`插件的调试并不像调试`JAVA`程序和`Maven`插件那么简单。在`IDEA`上直接点击`debug`启动相关操作就可以直接调试了。 需要实现在命令行设置调试模式。操作如下图: @@ -172,7 +177,7 @@ gradle wrapper 点击 **Edit Configurations** ![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004033_cd63df34_144669.png "remote1.png") 点开左边的"**+**"号,点击"**Remote**" -![添加remote](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004113_df83ee8d_144669.png "remote2.png") +![添加remote](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/set-gradle-debug-name.png "remote2.png") ### 执行调试 完成上面的操作后即可用`debug`调试进入插件和`smart-doc`了,然后查看`smart-doc`的执行情况。操作如下图 -![执行调试](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/004808_63ad37db_144669.png "debug3.png") \ No newline at end of file +![执行调试](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/gradle-run-debug.png "debug3.png") \ No newline at end of file diff --git a/docs/zh-cn/plugins/maven.md b/docs/zh-cn/plugins/maven.md index 266795e..05877f0 100644 --- a/docs/zh-cn/plugins/maven.md +++ b/docs/zh-cn/plugins/maven.md @@ -146,6 +146,10 @@ mvn -Dfile.encoding=UTF-8 smart-doc:postman mvn -Dfile.encoding=UTF-8 smart-doc:openapi // 生成文档推送到Torna平台 mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest +// 生成word格式文档,推荐使用smart-doc 3.0.2及更高版本 +mvn -Dfile.encoding=UTF-8 smart-doc:word +// 生成jmeter性能压测脚本 +mvn -Dfile.encoding=UTF-8 smart-doc:jmeter // Apache Dubbo RPC文档 // Generate html @@ -205,7 +209,7 @@ OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos" ## 添加断点 添加断点如图所示 -![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/232807_f88b94b2_144669.png "maven-debug1.png") +![输入图片说明](https://github.com/smart-doc-group/smart-doc-group.github.io/raw/master/docs/_images/maven-plugin-debug.png "maven-debug1.png") ## Debug模式运行构建目标 `maven`插件在`idea`中运行`debug`非常简单,操作如下图。