upgrade to 1.8.3
This commit is contained in:
oppofind
parent
dd8a594a8a
commit
3b73041a19
|
|
@ -190,8 +190,9 @@
|
|||
4. 支持@Validated 分组
|
||||
|
||||
#### 版本号：1.8.3
|
||||
- 更新日期: 2020-xx
|
||||
- 更新日期: 2020-03-21
|
||||
- 更新内容：
|
||||
1. 增加对gitee #I1C1DF支持 。
|
||||
2. 修改smart-doc默认编码为utf-8。
|
||||
1. 增加从接口方法getter或者setter方法中读取注释。
|
||||
2. 修改smart-doc默认编码为utf-8，解决生成文档乱码问题。
|
||||
3. 增加对代码中@author tag的支持，支持多作者。
|
||||
|
||||
|
|
|
|||
228
README.md
228
README.md
|
|
@ -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.
|
||||
Of course you can also browse `http://localhost:8080/doc/api.html`,
|
||||
which looks a html like generated by `asciidoctor-maven-plugin` plugin.
|
||||
### Dependency
|
||||
#### maven
|
||||
## Add Maven plugin
|
||||
Add smart-doc-maven-plugin in your pom.xml.
|
||||
```
|
||||
<dependency>
|
||||
<plugin>
|
||||
<groupId>com.github.shalousun</groupId>
|
||||
<artifactId>smart-doc</artifactId>
|
||||
<artifactId>smart-doc-maven-plugin</artifactId>
|
||||
<version>[latest]</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<configuration>
|
||||
<!--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
|
||||
```
|
||||
testCompile 'com.github.shalousun:smart-doc:[latest]'
|
||||
```
|
||||
### Create a unit test
|
||||
Just running a unit test will allow Smart-doc to generate a very concise api document for you,
|
||||
which is much simpler than swagger.
|
||||
### 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:**
|
||||
```
|
||||
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);
|
||||
}
|
||||
{
|
||||
"allInOne": true, // whether to merge documents into one file, generally recommended as true
|
||||
"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.
|
||||
"outPath": "/src/main/resources" //Set the api document output path.
|
||||
}
|
||||
```
|
||||
**Detailed use case:**
|
||||
```
|
||||
public class ApiDocTest {
|
||||
Only three configuration items are required to use the smart-doc-maven-plugin to generate API documentation. In fact, only outPath must be configured.
|
||||
|
||||
@Test
|
||||
public void testBuilderControllersApi() {
|
||||
ApiConfig config = new ApiConfig();
|
||||
config.setServerUrl("http://localhost:8080");
|
||||
|
||||
//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");
|
||||
|
||||
//since smart-doc 1.7.5
|
||||
//corverd old AllIneOne.md file generated by smart-doc.
|
||||
config.setCoverOld(true);
|
||||
//since smart-doc 1.7.9, default is true
|
||||
config.setShowAuthor(false);
|
||||
//since smart-doc 1.7.5
|
||||
//set project name
|
||||
config.setProjectName("Your project name");
|
||||
// If you do not configure PackageFilters, it matches all controllers by default.
|
||||
// Configure multiple controller paths to be separated by commas
|
||||
config.setPackageFilters("com.power.doc.controller");
|
||||
|
||||
//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);
|
||||
}
|
||||
**Detailed configuration content:**
|
||||
|
||||
When you need to use smart-doc to generate more API document information, you can add detailed configuration content.
|
||||
```
|
||||
{
|
||||
"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
|
||||
}
|
||||
],
|
||||
|
||||
"errorCodeDictionaries": [{// error code list, no need to set
|
||||
"title": "title",
|
||||
"enumClassName": "com.power.doc.enums.ErrorCodeEnum", // Error code enumeration class
|
||||
"codeField": "code", // Code field name of the error code
|
||||
"descField": "desc" // Field name corresponding to the error code description
|
||||
}],
|
||||
|
||||
"revisionLogs": [// Set document change records, no need to set
|
||||
{
|
||||
"version": "1.0", // Document version number
|
||||
"status": "update", // Change operation status, generally: create, update, etc.
|
||||
"author": "author", // Document change author
|
||||
"remarks": "desc" // Change description
|
||||
}
|
||||
],
|
||||
"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.
|
||||
{
|
||||
"name": "code", // Override the response code field
|
||||
"desc": "Response code", // Override field comment of response code
|
||||
"value": "00000" // Set the value of the response code
|
||||
}
|
||||
],
|
||||
"requestHeaders": [// Set global request headers, no need to set
|
||||
{
|
||||
"name": "token",
|
||||
"type": "string",
|
||||
"desc": "desc",
|
||||
"required": false,
|
||||
"since": "-"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
**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.
|
||||
|
||||
|
||||
## 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
|
||||
#### Interface header rendering
|
||||
|
||||
|
|
@ -138,14 +167,17 @@ public class ApiDocTest {
|
|||
|
||||
#### Response parameter example renderings
|
||||
|
||||
## 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
|
||||
you can build with the following commands. (Java 1.8 is required to build the master branch)
|
||||
```
|
||||
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
|
||||
- [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki)
|
||||
|
||||
|
|
|
|||
|
|
@ -156,8 +156,12 @@ mvn -Dfile.encoding=UTF-8 smart-doc:postman
|
|||
```
|
||||
mvn clean install -Dmaven.test.skip=true
|
||||
```
|
||||
## Releases
|
||||
[发布记录](https://gitee.com/sunyurepository/smart-doc/blob/master/CHANGELOG.md)
|
||||
## Contributors
|
||||
感谢下列提交者
|
||||
|
||||
- [@zuonidelaowang](https://github.com/zuonidelaowang)
|
||||
- [@su-qiu](https://github.com/su-qiu)
|
||||
- [@qinkangdeid](https://github.com/qinkangdeid)
|
||||
## Other reference
|
||||
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
|
||||
- [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800)
|
||||
|
|
|
|||
6
pom.xml
6
pom.xml
|
|
@ -5,7 +5,7 @@
|
|||
<modelVersion>4.0.0</modelVersion>
|
||||
<artifactId>smart-doc</artifactId>
|
||||
<packaging>jar</packaging>
|
||||
<version>1.8.2</version>
|
||||
<version>1.8.3</version>
|
||||
|
||||
<name>smart-doc</name>
|
||||
<url>https://github.com/shalousun/smart-doc.git</url>
|
||||
|
|
@ -44,7 +44,7 @@
|
|||
<dependency>
|
||||
<groupId>com.ibeetl</groupId>
|
||||
<artifactId>beetl</artifactId>
|
||||
<version>3.0.16.RELEASE</version>
|
||||
<version>3.0.20.RELEASE</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.thoughtworks.qdox</groupId>
|
||||
|
|
@ -119,7 +119,7 @@
|
|||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-javadoc-plugin</artifactId>
|
||||
<version>3.1.1</version>
|
||||
<version>3.2.0</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>package</phase>
|
||||
|
|
|
|||
Loading…
Reference in New Issue