-
Notifications
You must be signed in to change notification settings - Fork 280
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
164 additions
and
164 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,164 +1,164 @@ | ||
| <h1 align="center">Smart-Doc Project</h1> | ||
|
|
||
| [中文文档](https://github.com/shalousun/smart-doc/blob/master/README_CN.md) | ||
|
|
||
| ## Introduce | ||
| Smart-doc is a java restful api document generation tool. Smart-doc is based on interface source code analysis to generate interface documents, and zero annotation intrusion. | ||
| You only need to write java standard comments when developing, smart-doc can help you generate a simple and clear markdown | ||
| Or a static html document. If you are tired of the numerous annotations and strong intrusion code contamination of document tools like swagger, then hug smart-doc! | ||
| ## Features | ||
| - Zero annotation, zero learning cost, only need to write standard java document comments. | ||
| - Automatic derivation based on source code interface definition, powerful return structure derivation support. | ||
| - Support Spring MVC, Spring Boot, Spring Boot Web Flux (Controller mode writing). | ||
| - Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture. | ||
| - Support JAVA's JSR303 parameter verification specification. | ||
| - Support for automatic generation of request examples based on request parameters. | ||
| - Support for generating json return value examples. | ||
| - Support for loading source code from outside the project to generate field comments (including the sources jar package). | ||
| - Support for generating multiple formats of documents: Markdown, HTML5, Asciidoctor,Postman Collection json. | ||
| - Support for exporting error codes and data dictionary codes to API documentation. | ||
| ## Getting started | ||
| [Smart-doc Samples](https://github.com/shalousun/smart-doc-demo.git)。 | ||
| ``` | ||
| # git clone https://github.com/shalousun/smart-doc-demo.git | ||
| ``` | ||
| 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 | ||
| ``` | ||
| <dependency> | ||
| <groupId>com.github.shalousun</groupId> | ||
| <artifactId>smart-doc</artifactId> | ||
| <version>1.8.1</version> | ||
| <scope>test</scope> | ||
| </dependency> | ||
| ``` | ||
| #### gradle | ||
| ``` | ||
| testCompile 'com.github.shalousun:smart-doc:1.8.1' | ||
| ``` | ||
| ### 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. | ||
|
|
||
| ``` | ||
| 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:** | ||
| ``` | ||
| public class ApiDocTest { | ||
| @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); | ||
| } | ||
| } | ||
| ``` | ||
| ### Generated document example | ||
| #### Interface header rendering | ||
|  | ||
| #### Request parameter example rendering | ||
|  | ||
| #### 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 | ||
| ``` | ||
| ## Other reference | ||
| - [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki) | ||
|
|
||
| ## Who is using | ||
| 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. | ||
|
|
||
|  | ||
| <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/yuanmengjiankang.png" title="yuanmengjiankang" width="260px" 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/puqie_gaitubao_100x100.jpg" title="puqie" width="83px" height="83px"/> | ||
| ## License | ||
| Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://github.com/shalousun/smart-doc/blob/master/license.txt) file for details. | ||
| ## Contact | ||
| Email： [email protected] | ||
| <h1 align="center">Smart-Doc Project</h1> | ||
|
|
||
| [中文文档](https://github.com/shalousun/smart-doc/blob/master/README_CN.md) | ||
|
|
||
| ## Introduce | ||
| Smart-doc is a java restful api document generation tool. Smart-doc is based on interface source code analysis to generate interface documents, and zero annotation intrusion. | ||
| You only need to write java standard comments when developing, smart-doc can help you generate a simple and clear markdown | ||
| Or a static html document. If you are tired of the numerous annotations and strong intrusion code contamination of document tools like swagger, then hug smart-doc! | ||
| ## Features | ||
| - Zero annotation, zero learning cost, only need to write standard java document comments. | ||
| - Automatic derivation based on source code interface definition, powerful return structure derivation support. | ||
| - Support Spring MVC, Spring Boot, Spring Boot Web Flux (Controller mode writing). | ||
| - Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture. | ||
| - Support JAVA's JSR303 parameter verification specification. | ||
| - Support for automatic generation of request examples based on request parameters. | ||
| - Support for generating json return value examples. | ||
| - Support for loading source code from outside the project to generate field comments (including the sources jar package). | ||
| - Support for generating multiple formats of documents: Markdown, HTML5, Asciidoctor,Postman Collection json. | ||
| - Support for exporting error codes and data dictionary codes to API documentation. | ||
| ## Getting started | ||
| [Smart-doc Samples](https://github.com/shalousun/smart-doc-demo.git)。 | ||
| ``` | ||
| # git clone https://github.com/shalousun/smart-doc-demo.git | ||
| ``` | ||
| 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 | ||
| ``` | ||
| <dependency> | ||
| <groupId>com.github.shalousun</groupId> | ||
| <artifactId>smart-doc</artifactId> | ||
| <version>[latest]</version> | ||
| <scope>test</scope> | ||
| </dependency> | ||
| ``` | ||
| #### 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. | ||
|
|
||
| ``` | ||
| 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:** | ||
| ``` | ||
| public class ApiDocTest { | ||
| @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); | ||
| } | ||
| } | ||
| ``` | ||
| ### Generated document example | ||
| #### Interface header rendering | ||
|  | ||
| #### Request parameter example rendering | ||
|  | ||
| #### 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 | ||
| ``` | ||
| ## Other reference | ||
| - [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki) | ||
|
|
||
| ## Who is using | ||
| 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. | ||
|
|
||
|  | ||
| <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/yuanmengjiankang.png" title="yuanmengjiankang" width="260px" 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/puqie_gaitubao_100x100.jpg" title="puqie" width="83px" height="83px"/> | ||
| ## License | ||
| Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://github.com/shalousun/smart-doc/blob/master/license.txt) file for details. | ||
| ## Contact | ||
| Email： [email protected] |