wanjia950611
/
smart-doc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

upgrade to 1.8.3

This commit is contained in:
oppofind 2020-03-21 20:54:40 +08:00
parent dd8a594a8a
commit 3b73041a19
4 changed files with 143 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
CHANGELOG.md
View File

@ -190,8 +190,9 @@
4. 支持@Validated 分组 4. 支持@Validated 分组
#### 版本号：1.8.3 #### 版本号：1.8.3
- 更新日期: 2020-xx - 更新日期: 2020-03-21
- 更新内容： - 更新内容：
1. 增加对gitee #I1C1DF支持 。 1. 增加从接口方法getter或者setter方法中读取注释。
2. 修改smart-doc默认编码为utf-8。 2. 修改smart-doc默认编码为utf-8，解决生成文档乱码问题。
3. 增加对代码中@author tag的支持，支持多作者。

226
README.md
View File

@ -25,112 +25,141 @@ Or a static html document. If you are tired of the numerous annotations and stro
This example already provides a static html document generated in advance. You can start the Spring Boot project and then go directly to `http://localhost:8080/doc/api.html` to view the interface documentation generated by smart-doc. This example already provides a static html document generated in advance. You can start the Spring Boot project and then go directly to `http://localhost:8080/doc/api.html` to view the interface documentation generated by smart-doc.
Of course you can also browse `http://localhost:8080/doc/api.html`, Of course you can also browse `http://localhost:8080/doc/api.html`,
which looks a html like generated by `asciidoctor-maven-plugin` plugin. which looks a html like generated by `asciidoctor-maven-plugin` plugin.
### Dependency ## Add Maven plugin
#### maven Add smart-doc-maven-plugin in your pom.xml.
``` ```
<dependency> <plugin>
<groupId>com.github.shalousun</groupId> <groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId> <artifactId>smart-doc-maven-plugin</artifactId>
<version>[latest]</version> <version>[latest]</version>
<scope>test</scope> <configuration>
</dependency> <!--Specify the configuration file used to generate the document-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--smart-doc implements automatic analysis of the dependency tree to load the source code of third-party dependencies. If some framework dependency libraries are not loaded, an error is reported, then use excludes to exclude-->
<excludes>
<!-The format is: groupId: artifactId; refer to the following->
<exclude>com.google.guava:guava</exclude>
</excludes>
</configuration>
<executions>
<execution>
<!--Comment out phase if you don't need to start smart-doc when compiling-->
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
``` ```
#### gradle ### Create a json config
Create a json configuration file in your project. The smart-doc-maven-plugin plugin will use this configuration information.
For example, create `/src/main/resources/smart-doc.json` in the project.
The configuration contents are as follows.
**Minimize configuration:**
``` ```
testCompile 'com.github.shalousun:smart-doc:[latest]' {
``` "allInOne": true, // whether to merge documents into one file, generally recommended as true
### Create a unit test "isStrict": false,//If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.
Just running a unit test will allow Smart-doc to generate a very concise api document for you, "outPath": "/src/main/resources" //Set the api document output path.
which is much simpler than swagger.
```
public class ApiDocTest {
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
//If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.
config.setStrict(true);
//When AllInOne is set to true, the document generation of all interfaces is merged into a Markdown or AsciiDoc document,
// and the error code list is output to the bottom of the document.
config.setAllInOne(true);
//Set the api document output path.
config.setOutPath("d:\\md");
//Generating Markdown documentation
ApiDocBuilder.buildApiDoc(config);
}
} }
``` ```
**Detailed use case:** Only three configuration items are required to use the smart-doc-maven-plugin to generate API documentation. In fact, only outPath must be configured.
**Detailed configuration content:**
When you need to use smart-doc to generate more API document information, you can add detailed configuration content.
``` ```
public class ApiDocTest { {
  "serverUrl": "http://127.0.0.1", // Set the server address, not required
  "isStrict": false, // whether to enable strict mode
  "allInOne": true, // whether to merge documents into one file, generally recommended as true
  "outPath": "D: // md2", // Specify the output path of the document
  "coverOld": true, // Whether to overwrite old files, mainly used for mardown file overwrite
  "packageFilters": "", // controller package filtering, multiple package names separated by commas
  "md5EncryptedHtmlName": false, // only used if each controller generates an html file
  "projectName": "smart-doc", // Configure your own project name
  "skipTransientField": true, // Not currently implemented
  "dataDictionaries": [// Configure the data dictionary, no need to set
    {
      "title": "Order Status", // The name of the data dictionary
      "enumClassName": "com.power.doc.enums.OrderEnum", // Data dictionary enumeration class name
      "codeField": "code", // The field name corresponding to the data dictionary dictionary code
      "descField": "desc" // Data dictionary object description information dictionary
    }
  ],
@Test   "errorCodeDictionaries": [{// error code list, no need to set
public void testBuilderControllersApi() {     "title": "title",
ApiConfig config = new ApiConfig();     "enumClassName": "com.power.doc.enums.ErrorCodeEnum", // Error code enumeration class
config.setServerUrl("http://localhost:8080");     "codeField": "code", // Code field name of the error code
    "descField": "desc" // Field name corresponding to the error code description
  }],
//If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.   "revisionLogs": [// Set document change records, no need to set
config.setStrict(true);     {
      "version": "1.0", // Document version number
//When AllInOne is set to true, the document generation of all interfaces is merged into a Markdown or AsciiDoc document,       "status": "update", // Change operation status, generally: create, update, etc.
// and the error code list is output to the bottom of the document.       "author": "author", // Document change author
config.setAllInOne(true);       "remarks": "desc" // Change description
    }
//Set the api document output path.   ],
config.setOutPath("d:\\md");   "customResponseFields": [// Customly add fields and comments. If api-doc encounters a field with the same name later, directly add a comment to the corresponding field. It is not necessary.
    {
//since smart-doc 1.7.5       "name": "code", // Override the response code field
//corverd old AllIneOne.md file generated by smart-doc.       "desc": "Response code", // Override field comment of response code
config.setCoverOld(true);       "value": "00000" // Set the value of the response code
//since smart-doc 1.7.9, default is true     }
config.setShowAuthor(false);   ],
//since smart-doc 1.7.5   "requestHeaders": [// Set global request headers, no need to set
//set project name     {
config.setProjectName("Your project name");       "name": "token",
// If you do not configure PackageFilters, it matches all controllers by default.       "type": "string",
// Configure multiple controller paths to be separated by commas       "desc": "desc",
config.setPackageFilters("com.power.doc.controller");       "required": false,
      "since": "-"
//Set the request header, if there is no request header, you don't need to set it.     }
config.setRequestHeaders(   ]
ApiReqHeader.header().setName("access_token").setType("string")
.setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"),
ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
);
//Output a list of error codes in the project, using for example:
List<ApiErrorCode> errorCodeList = new ArrayList<>();
for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
ApiErrorCode errorCode = new ApiErrorCode();
errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
errorCodeList.add(errorCode);
}
//not necessary
config.setErrorCodes(errorCodeList);
//Set the document change record,
//it is not necessary to have the document change record take effect only when setAllInOne is set to true.
config.setRevisionLogs(
RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("test").setStatus("create").setVersion("V1.0"),
RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("test2").setStatus("update").setVersion("V2.0")
);
//since 1.7.5
//add data dictionary
config.setDataDictionaries(
ApiDataDictionary.dict().setTitle("Order status").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
ApiDataDictionary.dict().setTitle("Order status1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
);
//Generating Markdown documentation
ApiDocBuilder.buildApiDoc(config);
}
} }
``` ```
**Note:** The above json configuration is completely converted into json using the smart-doc's ApiConfig.
So the project configuration can also refer to the introduction of smart-doc.
### Generated document
#### Use Maven command
```
// Generate html
mvn -Dfile.encoding = UTF-8 smart-doc: html
// Generate markdown
mvn -Dfile.encoding = UTF-8 smart-doc: markdown
// Generate adoc
mvn -Dfile.encoding = UTF-8 smart-doc: adoc
// Generate postman collection
mvn -Dfile.encoding = UTF-8 smart-doc: postman
```
**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.
View maven's coding
```
# mvn -version
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00)
Maven home: D:\ProgramFiles\maven\bin\..
Java version: 1.8.0_191, vendor: Oracle Corporation
Java home: D:\ProgramFiles\Java\jdk1.8.0_191\jre
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"
```
#### Use IntelliJ IDEA
On Use IntelliJ IDE, if you have added smart-doc-maven-plugin to the project,
you can directly find the plugin smart-doc plugin and click to generate API documentation.
![smart-doc-maven-plugin](https://raw.githubusercontent.com/shalousun/smart-doc-maven-plugin/master/images/idea.png)
## Use Junit Test
You can generate documentation by adding smart-doc dependencies directly to your project and then writing unit tests to start smart-doc.
But we still recommend that you use the smart-doc-maven-plugin plugin.
[Use smart-doc by junit test](https://github.com/smart-doc-group/smart-doc/wiki/Use-smart-doc-by-junit-test)
### Generated document example ### Generated document example
#### Interface header rendering #### Interface header rendering
![header](https://images.gitee.com/uploads/images/2019/1231/223538_be45f8a9_144669.png "header.png") ![header](https://images.gitee.com/uploads/images/2019/1231/223538_be45f8a9_144669.png "header.png")
@ -138,14 +167,17 @@ public class ApiDocTest {
![request-params](https://images.gitee.com/uploads/images/2019/1231/223710_88933f55_144669.png "request.png") ![request-params](https://images.gitee.com/uploads/images/2019/1231/223710_88933f55_144669.png "request.png")
#### Response parameter example renderings #### Response parameter example renderings
![response-fields](https://images.gitee.com/uploads/images/2019/1231/223817_32bea6dc_144669.png "response.png") ![response-fields](https://images.gitee.com/uploads/images/2019/1231/223817_32bea6dc_144669.png "response.png")
## Use Maven Plugin
Smart-doc provides a maven plugin to quickly integrate into the project to generate documentation.
It is recommended that you use plugins instead of the unit tests above. [smart-doc-maven-plugin](https://github.com/shalousun/smart-doc-maven-plugin)
## Building ## Building
you can build with the following commands. (Java 1.8 is required to build the master branch) you can build with the following commands. (Java 1.8 is required to build the master branch)
``` ```
mvn clean install -Dmaven.test.skip=true mvn clean install -Dmaven.test.skip=true
``` ```
## Contributors
Thanks to the following people who have submitted major pull requests:
- [@zuonidelaowang](https://github.com/zuonidelaowang)
- [@su-qiu](https://github.com/su-qiu)
- [@qinkangdeid](https://github.com/qinkangdeid)
## Other reference ## Other reference
- [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki) - [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki)

8
README_CN.md
View File

@ -156,8 +156,12 @@ mvn -Dfile.encoding=UTF-8 smart-doc:postman
``` ```
mvn clean install -Dmaven.test.skip=true mvn clean install -Dmaven.test.skip=true
``` ```
## Releases ## Contributors
[发布记录](https://gitee.com/sunyurepository/smart-doc/blob/master/CHANGELOG.md) 感谢下列提交者
- [@zuonidelaowang](https://github.com/zuonidelaowang)
- [@su-qiu](https://github.com/su-qiu)
- [@qinkangdeid](https://github.com/qinkangdeid)
## Other reference ## Other reference
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962) - [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
- [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800) - [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800)

6
pom.xml
View File

@ -5,7 +5,7 @@
<modelVersion>4.0.0</modelVersion> <modelVersion>4.0.0</modelVersion>
<artifactId>smart-doc</artifactId> <artifactId>smart-doc</artifactId>
<packaging>jar</packaging> <packaging>jar</packaging>
<version>1.8.2</version> <version>1.8.3</version>
<name>smart-doc</name> <name>smart-doc</name>
<url>https://github.com/shalousun/smart-doc.git</url> <url>https://github.com/shalousun/smart-doc.git</url>
@ -44,7 +44,7 @@
<dependency> <dependency>
<groupId>com.ibeetl</groupId> <groupId>com.ibeetl</groupId>
<artifactId>beetl</artifactId> <artifactId>beetl</artifactId>
<version>3.0.16.RELEASE</version> <version>3.0.20.RELEASE</version>
</dependency> </dependency>
<dependency> <dependency>
<groupId>com.thoughtworks.qdox</groupId> <groupId>com.thoughtworks.qdox</groupId>
@ -119,7 +119,7 @@
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId> <artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.1</version> <version>3.2.0</version>
<executions> <executions>
<execution> <execution>
<phase>package</phase> <phase>package</phase>