Skip to content

Commit

Permalink
merge to master
Browse files Browse the repository at this point in the history
  • Loading branch information
shalousun committed Jun 2, 2020
2 parents be51544 + 0eff326 commit 67649ca
Show file tree
Hide file tree
Showing 7 changed files with 184 additions and 8 deletions.
24 changes: 20 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ When you need to use smart-doc to generate more API document information, you ca
  "md5EncryptedHtmlName": false, // only used if each controller generates an html file
  "projectName": "smart-doc", // Configure your own project name
  "skipTransientField": true, // Not currently implemented
"requestFieldToUnderline":true, //convert request field to underline
"responseFieldToUnderline":true,//convert response field to underline
  "dataDictionaries": [// Configure the data dictionary, no need to set
    {
      "title": "Order Status", // The name of the data dictionary
Expand Down Expand Up @@ -110,6 +112,12 @@ When you need to use smart-doc to generate more API document information, you ca
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto" //Use custom PageRequestDto instead of JPA Pageable for document rendering.
}],
"rpcApiDependencies":[{ // Your Apache Dubbo api interface module dependency description.
"artifactId":"SpringBoot2-Dubbo-Api",
"groupId":"com.demo",
"version":"1.0.0"
}],
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",//dubbo consumer config example
  "requestHeaders": [// Set global request headers, no need to set
    {
      "name": "token",
Expand All @@ -127,13 +135,21 @@ So the project configuration can also refer to the introduction of smart-doc.
#### Run plugin with maven command
```
// Generate html
mvn -Dfile.encoding = UTF-8 smart-doc: html
mvn -Dfile.encoding = UTF-8 smart-doc:html
// Generate markdown
mvn -Dfile.encoding = UTF-8 smart-doc: markdown
mvn -Dfile.encoding = UTF-8 smart-doc:markdown
// Generate adoc
mvn -Dfile.encoding = UTF-8 smart-doc: adoc
mvn -Dfile.encoding = UTF-8 smart-doc:adoc
// Generate postman collection
mvn -Dfile.encoding = UTF-8 smart-doc: postman
mvn -Dfile.encoding = UTF-8 smart-doc:postman
// For Apache Dubbo Rpc
// Generate html
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-adoc
```
**Note:** Under the window system, if you use the maven command line to perform document generation,
non-English characters may be garbled, so you need to specify `-Dfile.encoding = UTF-8` during execution.
Expand Down
18 changes: 17 additions & 1 deletion README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ smart-doc-maven-plugin是smart-doc官方团队开发的`maven`插件,该插件
"md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
"projectName": "smart-doc",//配置自己的项目名称
"skipTransientField": true,//目前未实现
"requestFieldToUnderline":true, //自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7 版本开始
"responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7 版本开始
"dataDictionaries": [ //配置数据字典,没有需求可以不设置
{
"title": "订单状态", //数据字典的名称
Expand Down Expand Up @@ -101,6 +103,12 @@ smart-doc-maven-plugin是smart-doc官方团队开发的`maven`插件,该插件
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
}],
"rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖,配置后输出到文档方便使用者集成
"artifactId":"SpringBoot2-Dubbo-Api",
"groupId":"com.demo",
"version":"1.0.0"
}],
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置,用于方便集成方可以快速集成
"requestHeaders": [ //设置请求头,没有需求可以不设置
{
"name": "token",
Expand Down Expand Up @@ -131,6 +139,14 @@ mvn -Dfile.encoding=UTF-8 smart-doc:markdown
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postmanjson数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// Apache Dubbo Rpc文档
// Generate html
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding = UTF-8 smart-doc:rpc-adoc
```
**注意:** 尤其在window系统下,如果实际使用maven命令行执行文档生成,可能会出现乱码,因此需要在执行时指定`-Dfile.encoding=UTF-8`

Expand All @@ -147,7 +163,7 @@ OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"
#### Run plugin in IDEA
当你使用Idea时,可以通过maven Helper插件选择生成何种文档。

![idea中smart-doc-maven插件使用](https://images.gitee.com/uploads/images/2019/1215/004902_b0c153d6_144669.png "idea.png")
![idea中smart-doc-maven插件使用](https://images.gitee.com/uploads/images/2020/0602/213139_739a4d41_144669.png "maven_plugin_tasks.png")

### Generated document example
[点击查看文档生成文档效果图](https://gitee.com/sunyurepository/smart-doc/wikis/文档效果图?sort_id=1652819)
Expand Down
Binary file modified images/idea.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 3 additions & 3 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>1.0.7</version>
<version>1.0.8</version>
<packaging>maven-plugin</packaging>

<name>smart-doc-maven-plugin</name>
Expand Down Expand Up @@ -71,7 +71,7 @@
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.8.6</version>
<version>1.8.7</version>
</dependency>
</dependencies>
<build>
Expand All @@ -96,7 +96,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.1.0</version>
<version>3.2.1</version>
<executions>
<execution>
<phase>package</phase>
Expand Down
48 changes: 48 additions & 0 deletions src/main/java/com/smartdoc/mojo/RpcAdocMojo.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/*
* smart-doc https://github.com/shalousun/smart-doc
*
* Copyright (C) 2018-2020 smart-doc
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.smartdoc.mojo;

import com.power.doc.builder.rpc.RpcAdocBuilder;
import com.power.doc.model.ApiConfig;
import com.thoughtworks.qdox.JavaProjectBuilder;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.ResolutionScope;

/**
* @author yu 2020/5/26.
*/
@Execute(phase = LifecyclePhase.COMPILE)
@Mojo(name = "rpc-adoc", requiresDependencyResolution = ResolutionScope.COMPILE)
public class RpcAdocMojo extends BaseDocsGeneratorMojo {

@Override
public void executeMojo(ApiConfig apiConfig, JavaProjectBuilder javaProjectBuilder) {
try {
RpcAdocBuilder.buildApiDoc(apiConfig, javaProjectBuilder);
} catch (Exception e) {
getLog().error(e);
}
}
}
48 changes: 48 additions & 0 deletions src/main/java/com/smartdoc/mojo/RpcHtmlMojo.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/*
* smart-doc https://github.com/shalousun/smart-doc
*
* Copyright (C) 2018-2020 smart-doc
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.smartdoc.mojo;

import com.power.doc.builder.rpc.RpcHtmlBuilder;
import com.power.doc.model.ApiConfig;
import com.thoughtworks.qdox.JavaProjectBuilder;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.ResolutionScope;

/**
* @author yu 2020/5/26.
*/
@Execute(phase = LifecyclePhase.COMPILE)
@Mojo(name = "rpc-html", requiresDependencyResolution = ResolutionScope.COMPILE)
public class RpcHtmlMojo extends BaseDocsGeneratorMojo {

@Override
public void executeMojo(ApiConfig apiConfig, JavaProjectBuilder javaProjectBuilder) {
try {
RpcHtmlBuilder.buildApiDoc(apiConfig, javaProjectBuilder);
} catch (Exception e) {
getLog().error(e);
}
}
}
48 changes: 48 additions & 0 deletions src/main/java/com/smartdoc/mojo/RpcMarkdownMojo.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/*
* smart-doc https://github.com/shalousun/smart-doc
*
* Copyright (C) 2018-2020 smart-doc
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.smartdoc.mojo;

import com.power.doc.builder.rpc.RpcMarkdownBuilder;
import com.power.doc.model.ApiConfig;
import com.thoughtworks.qdox.JavaProjectBuilder;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.ResolutionScope;

/**
* @author yu 2020/5/26.
*/
@Execute(phase = LifecyclePhase.COMPILE)
@Mojo(name = "rpc-markdown", requiresDependencyResolution = ResolutionScope.COMPILE)
public class RpcMarkdownMojo extends BaseDocsGeneratorMojo {

@Override
public void executeMojo(ApiConfig apiConfig, JavaProjectBuilder javaProjectBuilder) {
try {
RpcMarkdownBuilder.buildApiDoc(apiConfig, javaProjectBuilder);
} catch (Exception e) {
getLog().error(e);
}
}
}

0 comments on commit 67649ca

Please sign in to comment.