From 3b73041a19d691a813c3124864a43fc66d75f699 Mon Sep 17 00:00:00 2001 From: oppofind <836575280@qq.com> Date: Sat, 21 Mar 2020 20:54:40 +0800 Subject: [PATCH] upgrade to 1.8.3 --- CHANGELOG.md | 7 +- README.md | 228 +++++++++++++++++++++++++++++---------------------- README_CN.md | 8 +- pom.xml | 6 +- 4 files changed, 143 insertions(+), 106 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e702c95..a013e8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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的支持，支持多作者。 diff --git a/README.md b/README.md index 820efbe..9b279f5 100644 --- a/README.md +++ b/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. ``` - + com.github.shalousun - smart-doc + smart-doc-maven-plugin [latest] - test - + + + ./src/main/resources/smart-doc.json + + + + com.google.guava:guava + + + + + + compile + + html + + + + ``` -#### 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 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. + +![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 #### Interface header rendering ![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") #### Response parameter example renderings ![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 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) diff --git a/README_CN.md b/README_CN.md index 4359e8b..fc1e556 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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) diff --git a/pom.xml b/pom.xml index 65b8404..f505b95 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 smart-doc jar - 1.8.2 + 1.8.3 smart-doc https://github.com/shalousun/smart-doc.git @@ -44,7 +44,7 @@ com.ibeetl beetl - 3.0.16.RELEASE + 3.0.20.RELEASE com.thoughtworks.qdox @@ -119,7 +119,7 @@ org.apache.maven.plugins maven-javadoc-plugin - 3.1.1 + 3.2.0 package