From 6e3399aa88e602dd71b65277819c327f84d8ef94 Mon Sep 17 00:00:00 2001 From: oppofind <836575280@qq.com> Date: Mon, 7 Dec 2020 00:14:51 +0800 Subject: [PATCH] support create debug page --- CHANGELOG.md | 1 + README.md | 1 + README_CN.md | 28 ++-- .../power/doc/builder/HtmlApiDocBuilder.java | 6 +- .../com/power/doc/builder/OpenApiBuilder.java | 5 +- .../doc/constants/DocGlobalConstants.java | 2 + .../java/com/power/doc/model/ApiConfig.java | 19 ++- .../template/SpringBootDocBuildTemplate.java | 1 + src/main/resources/template/mock.html | 139 ++++++++++++++++++ 9 files changed, 178 insertions(+), 24 deletions(-) create mode 100644 src/main/resources/template/mock.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 23c05f1..03f40a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ 3. 使用postman collection 2.0的支持。 4. 添加分组支持group。 5. 修改mock的依稀bug和增强使用 + 6. 支出创建debug页面 #### 版本号：1.9.9.1 - 更新日期: 2020-11-23 - 更新内容： diff --git a/README.md b/README.md index ac1d81a..a149554 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,7 @@ When you need to use smart-doc to generate more API document information, you ca   "projectName": "smart-doc", // Configure your own project name   "skipTransientField": true, // Not currently implemented "style":"xt256", //set highlight + "createDebugPage": true, "sortByTitle":false,//Sort by interface title, the default value is false "requestFieldToUnderline":true, //convert request field to underline "inlineEnum":true,// Set to true to display enumeration details in the parameter table diff --git a/README_CN.md b/README_CN.md index 63dd431..fff0b97 100644 --- a/README_CN.md +++ b/README_CN.md @@ -94,6 +94,7 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc "allInOne": true, //是否将文档合并到一个文件中，一般推荐为true "outPath": "D://md2", //指定文档的输出路径 "coverOld": true, //是否覆盖旧的文件，主要用于mardown文件覆盖 + "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面 "packageFilters": "",//controller包过滤，多个包用英文逗号隔开 "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用 "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置 @@ -112,46 +113,39 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2 "org.springframework.ui.ModelMap" ], - "dataDictionaries": [ //配置数据字典，没有需求可以不设置 - { + "dataDictionaries": [{ //配置数据字典，没有需求可以不设置 "title": "http状态码字典", //数据字典的名称 "enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称 "codeField": "code",//数据字典字典码对应的字段名称 "descField": "message"//数据字典对象的描述信息字典 - } - ], + }], "errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置 "title": "title", "enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类 "codeField": "code",//错误码的code码字段名称 "descField": "message"//错误码的描述信息对应的字段名 }], - "revisionLogs": [ //设置文档变更记录，没有需求可以不设置 - { + "revisionLogs": [{ "version": "1.0", //文档版本号 "status": "update", //变更操作状态，一般为：创建、更新等 "author": "author", //文档变更作者 "remarks": "desc" //变更描述 } ], - "customResponseFields": [ //自定义添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释，非必须 - { + "customResponseFields": [{ //自定义添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释，非必须 "name": "code",//覆盖响应码字段 "desc": "响应代码",//覆盖响应码的字段注释 "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名 "value": "00000"//设置响应码的值 - } - ], - "requestHeaders": [ //设置请求头，没有需求可以不设置 - { + }], + "requestHeaders": [{ //设置请求头，没有需求可以不设置 "name": "token",//请求头名称 "type": "string",//请求头类型 "desc": "desc",//请求头描述信息 "value":"token请求头的值",//不设置默认null "required": false,//是否必须 "since": "-"//什么版本添加的改请求头 - } - ], + }], "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成 "artifactId":"SpringBoot2-Dubbo-Api", "groupId":"com.demo", @@ -168,12 +162,10 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc "responseBodyAdvice":{ //自smart-doc 1.9.8起，ResponseBodyAdvice统一返回设置，可用ignoreResponseBodyAdvice tag来忽略 "className":"com.power.common.model.CommonResult" //通用响应体 }, - "sourceCodePaths": [ //设置代码路径, 插件已经能够自动下载发布的源码包，没必要配置 - { + "sourceCodePaths": [{ //设置代码路径, 插件已经能够自动下载发布的源码包，没必要配置 "path": "src/main/java", "desc": "测试" - } - ] + }] } ``` 上面的JSON配置实例中只有"outPath"是必填项。 diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index 7d3ee5f..2381430 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -88,7 +88,11 @@ public class HtmlApiDocBuilder { if (StringUtils.isNotEmpty(config.getAllInOneDocFileName())) { INDEX_HTML = config.getAllInOneDocFileName(); } - builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_HTML_TPL, INDEX_HTML); + if(config.isCreateDebugPage()){ + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, DEBUG_PAGE_TPL, DEBUG_PAGE_TPL); + } else { + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_HTML_TPL, INDEX_HTML); + } } else { List apiDocDictList = builderTemplate.buildDictionary(config, javaProjectBuilder); buildIndex(apiDocList, config); diff --git a/src/main/java/com/power/doc/builder/OpenApiBuilder.java b/src/main/java/com/power/doc/builder/OpenApiBuilder.java index 7773787..3ce49fb 100644 --- a/src/main/java/com/power/doc/builder/OpenApiBuilder.java +++ b/src/main/java/com/power/doc/builder/OpenApiBuilder.java @@ -72,8 +72,6 @@ public class OpenApiBuilder { Gson gson = new GsonBuilder().setPrettyPrinting().create(); String data = gson.toJson(json); FileUtil.nioWriteFile(data, filePath); - - } /** @@ -230,7 +228,7 @@ public class OpenApiBuilder { detail = new HashMap<>(); detail.put("type", apiParam.getType()); detail.put("description", apiParam.getDesc()); - detail.put("example", apiParam.getValue()); + detail.put("example", DocUtil.handleJsonStr(apiParam.getValue())); if ("file".equals(apiParam.getType())) { if (apiParam.isHasItems()) { detail.put("type", "array"); @@ -346,6 +344,7 @@ public class OpenApiBuilder { parameters.put("name", header.getName()); parameters.put("description", header.getDesc()); parameters.put("required", header.isRequired()); + parameters.put("example",header.getValue()); parameters.put("schema", buildParametersSchema(header)); parameters.put("in", "header"); parametersList.add(parameters); diff --git a/src/main/java/com/power/doc/constants/DocGlobalConstants.java b/src/main/java/com/power/doc/constants/DocGlobalConstants.java index 6849a59..f4fc80d 100644 --- a/src/main/java/com/power/doc/constants/DocGlobalConstants.java +++ b/src/main/java/com/power/doc/constants/DocGlobalConstants.java @@ -51,6 +51,8 @@ public interface DocGlobalConstants { String MARKDOWN_CSS_TPL = "markdown.css"; + String DEBUG_PAGE_TPL = "mock.html"; + String ALL_IN_ONE_CSS = "AllInOne.css"; String RPC_API_DOC_ADOC_TPL = "dubbo/Dubbo.adoc"; diff --git a/src/main/java/com/power/doc/model/ApiConfig.java b/src/main/java/com/power/doc/model/ApiConfig.java index 8d7713d..cf8825d 100644 --- a/src/main/java/com/power/doc/model/ApiConfig.java +++ b/src/main/java/com/power/doc/model/ApiConfig.java @@ -255,6 +255,11 @@ public class ApiConfig { private String style; + /** + * create debug page + */ + private boolean createDebugPage; + public String getServerUrl() { return serverUrl; } @@ -564,6 +569,14 @@ public class ApiConfig { this.style = style; } + public boolean isCreateDebugPage() { + return createDebugPage; + } + + public void setCreateDebugPage(boolean createDebugPage) { + this.createDebugPage = createDebugPage; + } + @Override public String toString() { final StringBuilder sb = new StringBuilder("{"); @@ -639,8 +652,10 @@ public class ApiConfig { .append(displayActualType); sb.append(",\"responseBodyAdvice\":") .append(responseBodyAdvice); - sb.append(",\"style\":") - .append(style); + sb.append(",\"style\":\"") + .append(style).append('\"'); + sb.append(",\"createDebugPage\":") + .append(createDebugPage); sb.append('}'); return sb.toString(); } diff --git a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java index 6834396..677599b 100644 --- a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java @@ -669,6 +669,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { List queryParams = new ArrayList<>(); List bodyParams = new ArrayList<>(); for (ApiParam param : paramList) { + param.setValue(StringUtil.removeQuotes(param.getValue())); if (param.isPathParam()) { param.setId(pathParams.size() + 1); pathParams.add(param); diff --git a/src/main/resources/template/mock.html b/src/main/resources/template/mock.html new file mode 100644 index 0000000..c27901d --- /dev/null +++ b/src/main/resources/template/mock.html @@ -0,0 +1,139 @@ +<%if(isNotEmpty(projectName)){%>${projectName}<%}else{%>API Reference<%}%>
<%if(isNotEmpty(revisionLogList)){%>
<%for(revisionLog in revisionLogList){%><%}%>
VersionUpdate TimeStatusAuthorDescription

${revisionLog.version}

${revisionLog.revisionTime}

${revisionLog.status}

${revisionLog.author}

${revisionLog.remarks}

<%}%><%for(api in apiDocList){%>

${api.order}. ${api.desc}

<%for(doc in api.list){%>

<%if(doc.deprecated){%>${api.order}.${doc.order}. ${doc.desc}<%}else{%>${api.order}.${doc.order}. ${doc.desc}<%}%>

Type: ${doc.type}

<%if(isNotEmpty(doc.author)){%>

Author: ${doc.author}

<%}%>

Content-Type: ${doc.contentType}

Description: ${doc.detail}

<%if(isNotEmpty(doc.requestHeaders)){%>

Request-headers:

<%for(header in doc.requestHeaders){%><%}%>
HeaderValueTypeRequiredDescription

${header.name}

${header.type}

${header.required}

${header.desc}

<%}%><%if(isNotEmpty(doc.pathParams)){%>

Path-parameters:

<%for(param in doc.pathParams){%><%}%>
ParameterValueRequiredTypeDescription

${param.field}

${param.type}

${param.required}

${param.desc}

<%}%><%if(isNotEmpty(doc.queryParams)){%>

Query-parameters:

<%for(param in doc.queryParams){%><%}%>
ParameterValueTypeRequiredDescription

${param.field}

${param.type}

${param.required}

${param.desc}

<%}%><%if(isNotEmpty(doc.requestParams)){%>

Body-parameters:

<%for(param in doc.requestParams){%><%}%>
ParameterTypeRequiredDescription

${param.field}

${param.type}

${param.required}

${param.desc}

<%}%><%if(isNotEmpty(doc.requestExample.jsonBody)&&isRequestExample){%>

Request-body:

<%}%><%if(isNotEmpty(doc.responseParams)){%>

Response-fields:

<%for(param in doc.responseParams){%><%}%>
FieldTypeDescriptionSince

${param.field}

${param.type}

${param.desc}

${param.version}

<%}%>

<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%>

Response-example:

${doc.responseUsage}
<%}%><%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%>

Curl-example:

${doc.requestUsage}
<%}%>
<%}%>
<%}%><%if(isNotEmpty(errorCodeList)){%>

${apiDocList.~size+1}. ${errorListTitle}

<%for(error in errorCodeList){%><%}%>
Error codeDescription

${error.value}

${error.desc}

<%}%><%if(isNotEmpty(dictList)){%>

${dictListOrder}. ${dictListTitle}

<% for(dict in dictList){ %>

${dictListOrder}.${dict.order}. ${dict.title}

<%for(dataDict in dict.dataDictList){%><%}%>
CodeTypeDescription

${dataDict.value}

${dataDict.type}

${dataDict.desc}

<%}%>
<%}%>
Generated by smart-doc at ${createTime}Suggestions,contact,support and error reporting on Gitee or Github
+ + +