2020-08-21 23:08:04 +08:00
< h1 align = "center" > Smart-Doc Project< / h1 >
2020-08-29 17:07:41 +08:00
2020-08-29 17:03:48 +08:00
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://github.com/shalousun/smart-doc/blob/master/README_CN.md)
2020-08-21 23:08:04 +08:00
## Introduce
2021-05-16 12:02:05 +08:00
smart-doc is a tool that supports both JAVA REST API and Apache Dubbo RPC interface document generation. Smart-doc is
based on interface source code analysis to generate interface documents, and zero annotation intrusion. You only need to
write Javadoc comments when developing, smart-doc can help you generate Markdown or HTML5 document. smart-doc does not
need to inject annotations into the code like Swagger.
2020-08-21 23:08:04 +08:00
## Features
2021-05-16 12:02:05 +08:00
2020-10-18 22:27:15 +08:00
- Zero annotation, zero learning cost, only need to write standard JAVA document comments.
2020-08-21 23:08:04 +08:00
- Automatic derivation based on source code interface definition, powerful return structure derivation support.
2020-10-18 22:27:15 +08:00
- Support Spring MVC, Spring Boot, Spring Boot Web Flux (Not support endpoint), Feign.
2020-08-21 23:08:04 +08:00
- Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture.
2020-10-18 22:27:15 +08:00
- Support JSR-303 parameter verification specification.
2020-08-21 23:08:04 +08:00
- Support for automatic generation of request examples based on request parameters.
2020-10-18 22:27:15 +08:00
- Support for generating JSON return value examples.
2021-05-16 12:02:05 +08:00
- Support for loading source code from outside the project to generate field comments (including the sources jar
package).
2020-12-06 13:37:55 +08:00
- Support for generating multiple formats of documents: Markdown,HTML5,Asciidoctor,Postman Collection 2.0+,OpenAPI 3.0.
2020-08-21 23:08:04 +08:00
- Support for exporting error codes and data dictionary codes to API documentation.
2020-12-15 01:19:30 +08:00
- The debug html5 page fully supports file upload and download testing.
2020-08-21 23:08:04 +08:00
- Support Apache Dubbo RPC.
2021-05-16 12:02:05 +08:00
2021-03-12 23:22:10 +08:00
## Best Practice
2021-05-16 12:02:05 +08:00
smart-doc + [Torna ](http://torna.cn ) form an industry-leading document generation and management solution, using
smart-doc to complete Java source code analysis and extract annotations to generate API documents without intrusion, and
automatically push the documents to the Torna enterprise-level interface document management platform.
2021-03-12 23:22:10 +08:00
2021-10-30 23:21:08 +08:00
2021-05-16 12:02:05 +08:00
2020-10-19 23:46:40 +08:00
## Getting Started
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
[Smart-doc Samples ](https://github.com/shalousun/smart-doc-demo.git )。
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
# git clone https://github.com/shalousun/smart-doc-demo.git
```
2021-05-16 12:02:05 +08:00
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.
2020-10-19 23:46:40 +08:00
### Add Maven Plugin
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
Add [smart-doc-maven-plugin ](https://github.com/smart-doc-group/smart-doc-maven-plugin ) in your pom.xml.
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
< plugin >
< groupId > com.github.shalousun< / groupId >
< artifactId > smart-doc-maven-plugin< / artifactId >
< version > [latest]< / version >
< 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 >
2020-09-03 21:19:22 +08:00
<!-- The format is: groupId: artifactId; refer to the following -->
2020-08-21 23:08:04 +08:00
< exclude > com.google.guava:guava< / exclude >
< / excludes >
<!-- Since version 1.0.8, the plugin provides includes support -->
<!-- smart - doc can automatically analyze the dependency tree to load all dependent source code. In principle, it will affect the efficiency of document construction, so you can use includes to let the plugin load the components you configure. -->
< includes >
2020-09-03 21:19:22 +08:00
<!-- The format is: groupId: artifactId; refer to the following -->
2020-08-21 23:08:04 +08:00
< include > com.alibaba:fastjson< / include >
< / includes >
< / configuration >
< executions >
< execution >
<!-- Comment out phase if you don't need to start smart - doc when compiling -->
< phase > compile< / phase >
< goals >
2020-12-27 21:20:23 +08:00
<!-- smart - doc provides html, openapi, markdown, adoc and other goals -->
2020-08-21 23:08:04 +08:00
< goal > html< / goal >
< / goals >
< / execution >
< / executions >
< / plugin >
```
2021-05-16 12:02:05 +08:00
2020-10-19 23:46:40 +08:00
### Configuration
2021-05-16 12:02:05 +08:00
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.
2020-08-21 23:08:04 +08:00
**Minimize configuration:**
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
{
"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.
2020-12-22 23:50:51 +08:00
"outPath": "src/main/resources/static/doc" //Set the api document output path.
2020-08-21 23:08:04 +08:00
}
```
2021-05-16 12:02:05 +08:00
Only the above three simple configuration items can make smart-doc-maven-plugin work. In fact, only the outPath
configuration item is necessary.
2020-08-21 23:08:04 +08:00
**Detailed configuration content:**
When you need to use smart-doc to generate more API document information, you can add detailed configuration content.
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
{
2021-01-01 14:24:50 +08:00
"serverUrl": "http://127.0.0.1", // Set the server address, not required
2021-07-09 17:26:25 +08:00
"pathPrefix": "", //Set the path prefix,not required。eg: Servlet ContextPath
2021-01-01 14:24:50 +08:00
"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
2020-11-21 02:15:13 +08:00
"style":"xt256", //set highlight
2020-12-27 21:20:23 +08:00
"createDebugPage": true,//Create a page that can be used to test your APIs like swagger
2020-12-27 17:06:49 +08:00
"language":"ENGLISH",//support ENGLISH and CHINESE
2021-01-01 14:24:50 +08:00
"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
2020-08-21 23:08:04 +08:00
"requestFieldToUnderline":true, //convert request field to underline
2021-01-01 14:24:50 +08:00
"responseFieldToUnderline":true,//convert response field to underline
"sortByTitle":false,//Sort by interface title, the default value is false
2021-03-24 22:38:07 +08:00
"showAuthor":true,// display author,default is true
2020-08-21 23:08:04 +08:00
"inlineEnum":true,// Set to true to display enumeration details in the parameter table
"recursionLimit":7,// Set the number of recursive executions to avoid stack overflow, the default is 7
"allInOneDocFileName":"index.html",//Customize the output document name
"requestExample":"true",//Whether to display the request example in the document, the default value is true.
"responseExample":"true",//Whether to display the response example in the document, the default is true.
2021-08-28 18:48:50 +08:00
"requestParamsTable": true, //@since 2.2.5,Whether to display the request params table in the document, the default value is true.
"responseParamsTable": true //@since 2.2.5,Whether to display the response params table in the document, the default is true.
2021-01-01 14:24:50 +08:00
"displayActualType":false,//display actual type of generic,
2021-03-21 11:10:41 +08:00
"urlSuffix":".do",//Support the url suffix of the old SpringMVC project,@since 2.1.0
2021-03-12 23:22:10 +08:00
"appKey": "xxx",// torna appKey, @since 2.0.9
"appToken": "xxx", //torna appToken,@since 2.0.9
"secret": "xx",//torna secret，
2021-09-06 22:33:29 +08:00
"replace":true, torna replace doc @since 2.2.4
2021-03-12 23:22:10 +08:00
"openUrl": "torna server/api/",//torna server url,@since 2.0.9
2021-03-24 22:38:07 +08:00
"tornaDebug":false,"// show log while set true
2020-08-22 19:05:12 +08:00
"ignoreRequestParams":[ //The request parameter object will be discarded when generating the document.@since 1.9.2
2021-01-01 14:24:50 +08:00
"org.springframework.ui.ModelMap"
2020-08-22 21:52:11 +08:00
],
2021-01-01 14:24:50 +08:00
"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
"revisionTime": "2020-12-31 10:30", //revision time
2021-01-01 15:08:45 +08:00
"author": "author", // Document change author
2021-01-01 14:24:50 +08:00
"status": "update", // Change operation status, generally: create, update, etc.
"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
2020-08-21 23:08:04 +08:00
}],
2021-04-09 23:16:08 +08:00
"customRequestFields": [{//@since 2.1.3
2021-04-09 17:56:50 +08:00
"name":"code", //Override the request code field
"desc":"request code", //Override field comment of response code
"ownerClassName":"com.xxx.constant.entity.Result",
"value":"200", // Set the value of the response code
"required":true,
"ignore":false
}],
2020-08-21 23:08:04 +08:00
"apiObjectReplacements": [{ // Supports replacing specified objects with custom objects to complete document rendering
2021-01-01 14:24:50 +08:00
"className": "org.springframework.data.domain.Pageable",
"replacementClassName": "com.power.doc.model.PageRequestDto" //Use custom PageRequestDto instead of JPA Pageable for document rendering.
2020-08-21 23:08:04 +08:00
}],
2021-01-01 14:24:50 +08:00
"rpcApiDependencies":[{ // Your Apache Dubbo api interface module dependency description.
"artifactId":"SpringBoot2-Dubbo-Api",
"groupId":"com.demo",
"version":"1.0.0"
2020-08-21 23:08:04 +08:00
}],
2021-01-01 14:24:50 +08:00
"apiConstants": [{//Configure your own constant class, smart-doc automatically replaces with a specific value when parsing to a constant
"constantsClassName": "com.power.doc.constants.RequestParamConstant"
}],
2020-11-05 23:57:45 +08:00
"responseBodyAdvice":{ //Support ResponseBodyAdvice
2021-01-01 14:24:50 +08:00
"className":"com.power.common.model.CommonResult" // Standard POJO for Response
2020-11-05 23:57:45 +08:00
},
2021-04-25 21:37:32 +08:00
"requestBodyAdvice":{ //Support ResponseBodyAdvice
"className":"com.power.common.model.CommonResult" // Standard POJO for Request
},
2021-01-01 14:24:50 +08:00
"rpcConsumerConfig": "src/main/resources/consumer-example.conf",//dubbo consumer config example
"requestHeaders": [{// Set global request headers, no need to set
"name": "token",
"type": "string",
"desc": "desc",
"required": false,
2021-07-17 23:38:56 +08:00
"pathPatterns": "*",
"excludePathPatterns":"/app/page/**"
2021-01-01 14:24:50 +08:00
"since": "-"
2021-07-17 23:38:56 +08:00
}],
"requestParams": [ //Public request parameters (a scenario where public request parameters are processed through interceptors) ，
{
"name": "configPathParam",
"type": "string",
"desc": "desc",
"paramIn": "path", // path,query
"value":"testPath",//default is null
"required": false,
"since": "-",
"pathPatterns": "*",
"excludePathPatterns":"/app/page/**"
},
{
"name": "configQueryParam",
"type": "string",
"desc": "desc",
"paramIn": "query",
"value":"testQuery",
"required": false,
"since": "-",
"pathPatterns": "*",
"excludePathPatterns":"/app/page/**"
}
2021-08-28 16:39:33 +08:00
],
"groups": [ // Group different controllers, @since 2.2.5
{
"name": "test group",
"apis": "com.power.doc.controller.app.*"
}
2021-07-17 23:38:56 +08:00
]
2020-08-21 23:08:04 +08:00
}
```
2021-05-16 12:02:05 +08:00
**Note:** This JSON configuration can be converted into JSON using smart-doc's ApiConfig Object. So the project
configuration can also refer to the introduction of smart-doc.
2020-08-21 23:08:04 +08:00
### Generated document
2021-05-16 12:02:05 +08:00
2020-10-19 23:46:40 +08:00
#### Run Plugin with MAVEN command
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
// Generate html
2021-03-12 23:22:10 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:html
2020-08-21 23:08:04 +08:00
// Generate markdown
2021-03-12 23:22:10 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
2020-08-21 23:08:04 +08:00
// Generate adoc
2021-03-12 23:22:10 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
2020-08-21 23:08:04 +08:00
// Generate postman collection
2021-03-12 23:22:10 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// Generate document and send to Torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest
2020-08-21 23:08:04 +08:00
2020-09-16 21:55:27 +08:00
// Apache Dubbo RPC
2020-08-21 23:08:04 +08:00
// Generate html
2020-09-16 21:55:27 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
2020-08-21 23:08:04 +08:00
// Generate markdown
2020-09-16 21:55:27 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
2020-08-21 23:08:04 +08:00
// Generate adoc
2020-09-16 21:55:27 +08:00
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc
2021-05-15 00:41:18 +08:00
// Push dubbo rpc document to Torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc
2020-08-21 23:08:04 +08:00
```
2021-05-16 12:02:05 +08:00
**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.
2020-08-21 23:08:04 +08:00
View maven's coding
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
# 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"
```
2021-05-16 12:02:05 +08:00
2020-10-19 23:46:40 +08:00
#### Run Plugin in IDEA
2021-05-16 12:02:05 +08:00
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.
2020-08-21 23:08:04 +08:00
2021-05-16 12:02:05 +08:00
2020-10-19 23:46:40 +08:00
### Use Gradle Plugin
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
If you use gradle to build the project, you can refer to the documentation of the gradle plugin to integrate,
[smart-doc-gradle-plugin ](https://github.com/smart-doc-group/smart-doc-gradle-plugin/blob/master/README.md )
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
### Generated document example
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
#### Interface header rendering
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
#### Request parameter example rendering
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
#### Response parameter example renderings
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
## Building
2021-05-16 12:02:05 +08:00
2020-10-18 22:27:15 +08:00
You could build with the following commands. (Java 1.8 is required to build the master branch)
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
```
mvn clean install -Dmaven.test.skip=true
```
2021-05-16 12:02:05 +08:00
2021-01-01 13:58:34 +08:00
## TODO
2021-05-16 12:02:05 +08:00
2021-01-01 13:58:34 +08:00
- Jakarta RS-API 2.x
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
## Other reference
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
- [Smart-doc manual ](https://github.com/shalousun/smart-doc/wiki )
## Who is using
2021-05-16 12:02:05 +08:00
These are only part of the companies using smart-doc, for reference only. If you are using smart-doc,
please [add your company here ](https://github.com/shalousun/smart-doc/issues/12 ) to tell us your scenario to make
smart-doc better.
2020-08-21 23:08:04 +08:00
2021-07-10 10:33:57 +08:00
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/oneplus.png" title = "OnePlus" width = "83px" height = "83px" / >
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/xiaomi.png" title = "Xiaomi" width = "170px" height = "83px" / >
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/neusoft.png" title = "东软集团" width = "170px" height = "83px" / >
2021-07-10 00:00:04 +08:00
< img src = "https://www.hand-china.com/static/img/hand-logo.svg" title = "上海汉得信息技术股份有限公司" width = "260px" height = "83px" / >
2021-07-10 10:33:57 +08:00
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/shunfeng.png" title = "顺丰" width = "83px" height = "83px" / >
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/zhongkezhilian.png" title = "zhongkezhilian" width = "272px" height = "83px" / >
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/yuanmengjiankang.png" title = "yuanmengjiankang" width = "260px" height = "83px" / >
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/puqie_gaitubao_100x100.jpg" title = "puqie" width = "83px" height = "83px" / >
2021-05-16 12:02:05 +08:00
2021-07-10 10:33:57 +08:00
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/known-users/tianbo-tech.png" title = "tianbo tech" width = "127px" height = "70px" / >
2020-08-21 23:08:04 +08:00
2021-07-10 10:33:57 +08:00
## Acknowledgements
Thanks to [JetBrains SoftWare ](https://www.jetbrains.com ) for providing free Open Source license for this open source project.
2021-07-10 10:42:48 +08:00
< img src = "https://raw.githubusercontent.com/shalousun/smart-doc/dev/images/jetbrains-variant-3.png" width = "260px" height = "220px" / >
2020-08-21 23:08:04 +08:00
## License
2021-05-16 12:02:05 +08:00
Smart-doc is under the Apache 2.0 license. See the [LICENSE ](https://github.com/shalousun/smart-doc/blob/master/LICENSE )
file for details.
2020-08-21 23:08:04 +08:00
## Contact
2021-05-16 12:02:05 +08:00
2020-08-21 23:08:04 +08:00
Email：
