smart-doc定制记录

smart-doc 定制的探究。

官方文档

开源地址
https://gitee.com/smart-doc-team/smart-doc

文档地址
https://smart-doc-group.github.io/#/?id=smart-doc

内容定制

@param中mock使用|

原文档中 @param 使用的是 | 来分割参数描述与mock值的，这样导致了java doc的不可理解。希望改成自定义分割字符串。

追踪源码发现这块是硬编码的，包括：

com.power.doc.template.IDocBuildTemplate#paramCommentResolve 解析注释

com.power.doc.template.SpringBootDocBuildTemplate#createMockValue 解析创建mock值

@param中有\n生成markdown出错

因为 @param是按markdown的table输出的，\n的会破坏markdown的结构，导致table变形。

在com.power.doc.utils.DocUtil#getParamsComments 这里解析了变量名与对应的注释内容，这时的注释内容是含有\n字符的。这个方法
是个通用的方法，用来解析参数与注释值，调用自com.power.doc.template.SpringBootDocBuildTemplate#requestParams，
并解析后存储在ApiParam 的 desc 字段中，最终设置进ApiMethodReqParam 中的 queryParams 。

ApiMethodReqParam apiMethodReqParam = ApiMethodReqParam.builder()
                .setRequestParams(bodyParams)
                .setPathParams(pathParams)
                .setQueryParams(queryParams);

返回后被保存入了 ApiMethodDoc 的queryParams 。

查看模板AllInOne.btl

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

**Query-parameters:**

Parameter | Type|Description|Required|Since
---|---|---|---|---
<%
for(param in doc.queryParams){
%>
${param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
<%}%>
<%}%>

这里直接使用了param.desc 导致markdown拼接错误。

所以可以把desc 里的\n替换成<br>

多Method的情况生成Request-example出错

当RequestMapping 的method = {RequestMethod.GET, RequestMethod.POST}的时候生成的Request-example:是

1	curl -X GET, RequestMethod.POST] -i /risk/caseTicketListInit

这里, RequestMethod.POST应该是解析没有考虑到这种情况。

翻看源码
com.power.doc.template.SpringBootDocBuildTemplate#buildReqJson 生成请求参数的地方，
此时的methodType = [RequestMethod.GET, RequestMethod.POST]，而这里的判断

1
2
3

if (Methods.POST.getValue()
                .equals(methodType) || Methods.PUT.getValue()
                .equals(methodType)) {

就已经有问题了，走到else的分支流程中，调用com.power.doc.utils.CurlUtil#toCurl

这里提取methodType就出现了错误。

String methodType = request.getType();
if (methodType.contains(".")) {
	methodType = methodType.substring(methodType.indexOf(".") + 1);
}

应该先按,分割后在按.分割获取到对应的methodType。