add dubbo adoc template

This commit is contained in:
oppofind 2020-05-17 21:58:41 +08:00
parent fc82072114
commit 7140760a2b
12 changed files with 532 additions and 9 deletions

View File

@ -54,7 +54,7 @@ public class AdocDocBuilder {
}
/**
* Only for smart-doc-maven-plugin.
* Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig
* @param javaProjectBuilder ProjectDocConfigBuilder

View File

@ -53,7 +53,7 @@ public class ApiDocBuilder {
}
/**
* Only for smart-doc-maven-plugin.
* Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig
* @param javaProjectBuilder ProjectDocConfigBuilder

View File

@ -65,7 +65,7 @@ public class HtmlApiDocBuilder {
}
/**
* Only for smart-doc-maven-plugin.
* Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig
* @param javaProjectBuilder ProjectDocConfigBuilder

View File

@ -65,7 +65,7 @@ public class PostmanJsonBuilder {
}
/**
* Only for smart-doc-maven-plugin.
* Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig Object
* @param projectBuilder QDOX avaProjectBuilder

View File

@ -0,0 +1,53 @@
package com.power.doc.builder.rpc;
import com.power.doc.builder.ProjectDocConfigBuilder;
import com.power.doc.model.ApiConfig;
import com.power.doc.model.rpc.RpcApiDoc;
import com.power.doc.template.JavaDocBuildTemplate;
import com.thoughtworks.qdox.JavaProjectBuilder;
import java.util.List;
import static com.power.doc.constants.DocGlobalConstants.*;
/**
* @author yu 2020/5/17.
*/
public class RpcAdocBuilder {
private static final String API_EXTENSION = "RpcApi.adoc";
private static final String INDEX_DOC = "rpc-index.adoc";
/**
* build adoc
*
* @param config ApiConfig
*/
public static void builderApiDoc(ApiConfig config) {
JavaProjectBuilder javaProjectBuilder = new JavaProjectBuilder();
buildApiDoc(config, javaProjectBuilder);
}
/**
* Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig
* @param javaProjectBuilder ProjectDocConfigBuilder
*/
public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) {
config.setAdoc(true);
RpcDocBuilderTemplate builderTemplate = new RpcDocBuilderTemplate();
builderTemplate.checkAndInit(config);
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
JavaDocBuildTemplate docBuildTemplate = new JavaDocBuildTemplate();
List<RpcApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
if (config.isAllInOne()) {
builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, RPC_ALL_IN_ONE_ADOC_TPL, INDEX_DOC);
} else {
builderTemplate.buildApiDoc(apiDocList, config, RPC_API_DOC_ADOC_TPL, API_EXTENSION);
builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC);
}
}
}

View File

@ -29,7 +29,7 @@ public class RpcMarkdownBuilder {
}
/**
* Only for smart-doc-maven-plugin.
*Only for smart-doc maven plugin and gradle plugin.
*
* @param config ApiConfig
* @param javaProjectBuilder ProjectDocConfigBuilder

View File

@ -21,21 +21,25 @@ public interface DocGlobalConstants {
String API_DOC_ADOC_TPL = "ApiDoc.adoc";
String RPC_API_DOC_ADOC_TPL = "dubbo/Dubbo.adoc";
String ALL_IN_ONE_MD_TPL = "AllInOne.btl";
String ALL_IN_ONE_ADOC_TPL = "AllInOne.adoc";
String RPC_ALL_IN_ONE_ADOC_TPL = "dubbo/DubboAllInOne.adoc";
String ALL_IN_ONE_HTML_TPL = "AllInOne.html";
String HTML_API_DOC_TPL = "HtmlApiDoc.btl";
String ERROR_CODE_LIST_MD_TPL = "ErrorCodeList.btl";
String ERROR_CODE_LIST_ADOC_TPL = "ErrorCodeList.btl";
String ERROR_CODE_LIST_ADOC_TPL = "ErrorCodeList.adoc";
String ERROR_CODE_LIST_MD = "ErrorCodeList.md";
String ERROR_CODE_LIST_ADOC = "ErrorCodeList.md";
String ERROR_CODE_LIST_ADOC = "ErrorCodeList.adoc";
String DICT_LIST_MD = "Dictionary.md";
@ -53,9 +57,9 @@ public interface DocGlobalConstants {
String ALL_IN_ONE_CSS = "AllInOne.css";
String RPC_API_DOC_MD_TPL = "Dubbo.md";
String RPC_API_DOC_MD_TPL = "dubbo/Dubbo.md";
String RPC_ALL_IN_ONE_MD_TPL = "DubboAllIneOne.md";
String RPC_ALL_IN_ONE_MD_TPL = "dubbo/DubboAllInOne.md";
String POSTMAN_JSON = "/postman.json";

View File

@ -0,0 +1,60 @@
= ${desc}
*URI:* ${uri}
*Service:* ${name}
*Protocol:* ${protocol}
*Author:* ${author}
*Version:* ${version}
<%
for(doc in list){
%>
<%if(doc.deprecated){%>
== ~~${doc.desc}~~
<%}else{%>
## ${doc.desc}
<%}%>
*Definition* ${doc.methodDefinition}
<%if(isNotEmpty(doc.author)){%>
*Author:* ${doc.author}
<%}%>
*Description:* ${doc.detail}
<%if(isNotEmpty(doc.requestParams)){%>
*Request-parameters:*
[width="100%",options="header"]
[stripes=even]
|====================
|Parameter | Type|Description|Required|Since
<%
for(param in doc.requestParams){
%>
|${param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
<%}%>
|====================
<%}%>
<%if(isNotEmpty(doc.responseParams)){%>
*Response-fields:*
[width="100%",options="header"]
[stripes=even]
|====================
|Field | Type|Description|Since
<%
for(param in doc.responseParams){
%>
|${param.field}|${param.type}|${param.desc}|${param.version}
<%}%>
|====================
<%}%>
<% } %>

View File

@ -0,0 +1,111 @@
<%if(isNotEmpty(projectName)){%>
= ${projectName}
<%}%>
<%if(isNotEmpty(revisionLogList)){%>
[width="100%",options="header"]
[stripes=even]
|====================
|Version | Update Time | Status | Author | Description
<%
for(revisionLog in revisionLogList){
%>
${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks}
<%}%>
|====================
<%}%>
<%if(isNotEmpty(dependencyList)){%>
== Add dependency
----
<%
for(dependency in dependencyList){
%>
<dependency>
<groupId>${dependency.groupId}</groupId>
<artifactId>${dependency.artifactId}</artifactId>
<version>${dependency.version}</version>
</dependency>
<%}%>
----
<%}%>
<%
for(api in apiDocList){
%>
== ${api.desc}
*URI:* ${api.uri}
*Service:* ${api.name}
*Protocol:* ${api.protocol}
*Author:* ${api.author}
*Version:* ${api.version}
<%
for(doc in api.list){
%>
<%if(doc.deprecated){%>
=== ~~${doc.desc}~~
<%}else{%>
=== ${doc.desc}
<%}%>
*Definition* ${doc.methodDefinition}
<%if(isNotEmpty(doc.author)){%>
*Author:* ${doc.author}
<%}%>
*Description:* ${doc.detail}
<%if(isNotEmpty(doc.requestParams)){%>
*Request-parameters:*
[width="100%",options="header"]
[stripes=even]
|====================
|Parameter | Type|Description|Required|Since
<%
for(param in doc.requestParams){
%>
${param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
<%}%>
|====================
<%}%>
<%if(isNotEmpty(doc.responseParams)){%>
*Response-fields:*
[width="100%",options="header"]
[stripes=even]
|====================
|Field | Type|Description|Since
<%
for(param in doc.responseParams){
%>
${param.field}|${param.type}|${param.desc}|${param.version}
<%}%>
|====================
<%}%>
<%if(isNotEmpty(errorCodeList)){%>
== ${errorListTitle}
[width="100%",options="header"]
[stripes=even]
|====================
|Error code |Description
<%
for(error in errorCodeList){
%>
${error.value}|${error.desc}
<%}%>
|====================
<%}%>
<%}%>
<%}%>

View File

@ -0,0 +1,295 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="smart-doc">
<%if(isNotEmpty(projectName)){%><title>${projectName}</title><%}else{%><title>API Reference</title><%}%>
<link rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="AllInOne.css?v=${version}"/>
<script src="https://cdn.bootcss.com/jquery/1.12.2/jquery.js"></script>
</head>
<body class="book toc2 toc-left">
<div id="header"><%if(isNotEmpty(projectName)){%><h1>${projectName}</h1><%}%>
<div id="toc" class="toc2">
<div id="toctitle"><span>API Reference</span></div>
<ul id="accordion" class="sectlevel1"><%for(api in apiDocList){%><%if(apiLP.first){%>
<li class="open"><a class="dd" href="#_${api.desc}">${api.order}.&nbsp;${api.desc}</a>
<ul class="sectlevel2" style="display: block"><%for(doc in api.list){%>
<li><%if(doc.deprecated){%><a href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;<span
class="line-through">${doc.desc}</span></a><%}else{%><a
href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;${doc.desc}</a><%}%>
</li>
<%}%>
</ul>
</li>
<%}else{%>
<li><a class="dd" href="#_${api.desc}">${api.order}.&nbsp;${api.desc}</a>
<ul class="sectlevel2"><%for(doc in api.list){%>
<li><%if(doc.deprecated){%><a href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;<span
class="line-through">${doc.desc}</span></a><%}else{%><a
href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;${doc.desc}</a><%}%>
</li>
<%}%>
</ul>
</li>
<%}%><%}%><%if(isNotEmpty(errorCodeList)){%>
<li><a href="#_error_code_list">${apiDocList.~size+1}.${errorListTitle}</a></li>
<%}%><%if(isNotEmpty(dictList)){%>
<li><a class="dd" href="#_dict_list">${dictListOrder}.&nbsp;${dictListTitle}</a>
<ul class="sectlevel2"><%for(dict in dictList){%>
<li><a href="#_${dictListOrder}_${dict.order}_${dict.title}">${dictListOrder}.${dict.order}.&nbsp;${dict.title}</a>
</li>
<%}%>
</ul>
</li>
<%}%>
</ul>
</div>
</div>
<div id="content"><%if(isNotEmpty(revisionLogList)){%>
<div id="preamble">
<div class="sectionbody">
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Version</th>
<th class="tableblock halign-left valign-top">Update Time</th>
<th class="tableblock halign-left valign-top">Status</th>
<th class="tableblock halign-left valign-top">Author</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody><%for(revisionLog in revisionLogList){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${revisionLog.version}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${revisionLog.revisionTime}</p>
</td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${revisionLog.status}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${revisionLog.author}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${revisionLog.remarks}</p></td>
</tr>
<%}%>
</tbody>
</table>
</div>
</div>
<%}%><%for(api in apiDocList){%>
<div class="sect1"><h2 id="_${api.desc}"><a class="anchor" href="#_${api.desc}"></a><a class="link"
href="#_${api.desc}">${api.order}.&nbsp;${api.desc}</a>
</h2>
<div class="sectionbody"><%for(doc in api.list){%>
<div class="sect2"><h3 id="_${api.order}_${doc.order}_${doc.desc}"><a class="anchor"
href="#_${api.order}_${doc.order}_${doc.desc}"></a><%if(doc.deprecated){%><a
class="link" href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;<span
class="line-through">${doc.desc}</span></a><%}else{%><a class="link"
href="#_${api.order}_${doc.order}_${doc.desc}">${api.order}.${doc.order}.&nbsp;${doc.desc}</a><%}%>
</h3>
<div class="paragraph"><p><strong>URL:</strong><a href="${doc.url}" class="bare">&nbsp;${doc.url}</a>
</p></div>
<div class="paragraph"><p><strong>Type:</strong>&nbsp;${doc.type}</p></div>
<%if(isNotEmpty(doc.author)){%>
<div class="paragraph"><p><strong>Author:</strong>&nbsp;${doc.author}</p></div>
<%}%>
<div class="paragraph"><p><strong>Content-Type:</strong>&nbsp;${doc.contentType}</p></div>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${doc.detail}</p></div>
<%if(isNotEmpty(doc.requestHeaders)){%>
<div class="paragraph"><p><strong>Request-headers:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Header</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Since</th>
</tr>
</thead>
<tbody><%for(header in doc.requestHeaders){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${header.name}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${header.type}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${header.desc}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${header.required}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${header.since}</p></td>
</tr>
<%}%>
</tbody>
</table>
<%}%><%if(isNotEmpty(doc.requestParams)){%>
<div class="paragraph"><p><strong>Request-parameters:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Required</th>
<th class="tableblock halign-left valign-top">Since</th>
</tr>
</thead>
<tbody><%for(param in doc.requestParams){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.field}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.type}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.desc}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.required}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.version}</p></td>
</tr>
<%}%>
</tbody>
</table>
<%}%><%if(isNotEmpty(doc.requestUsage)){%>
<div class="paragraph"><p><strong>Request-example:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre>${doc.requestUsage}</pre>
</div>
</div>
<%}%><%if(isNotEmpty(doc.responseParams)){%>
<div class="paragraph"><p><strong>Response-fields:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Since</th>
</tr>
</thead>
<tbody><%for(param in doc.responseParams){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.field}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.type}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.desc}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${param.version}</p></td>
</tr>
<%}%>
</tbody>
</table>
<%}%><%if(isNotEmpty(doc.responseUsage)){%>
<div class="paragraph"><p><strong>Response-example:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre>${doc.responseUsage}</pre>
</div>
</div>
<%}%>
</div>
<%}%>
</div>
</div>
<%}%><%if(isNotEmpty(errorCodeList)){%>
<div class="sect1"><h2 id="_error_code_list"><a class="anchor" href="#_error_code_list"></a><a class="link"
href="#_error_code_list">${apiDocList.~size+1}.&nbsp;${errorListTitle}</a>
</h2>
<div class="sectionbody">
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Error code</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody><%for(error in errorCodeList){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${error.value}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${error.desc}</p></td>
</tr>
<%}%>
</tbody>
</table>
</div>
</div>
<%}%><%if(isNotEmpty(dictList)){%>
<div class="sect1"><h2 id="_dict_list"><a class="anchor" href="#_dict_list"></a><a class="link" href="#_dict_list">${dictListOrder}.&nbsp;${dictListTitle}</a>
</h2>
<div class="sectionbody"><% for(dict in dictList){ %>
<div class="sect2"><h3 id="_${dictListOrder}_${dict.order}_${dict.title}"><a class="anchor"
href="#_${dictListOrder}_${dict.order}_${dict.title}"></a><a
class="link" href="#_${dictListOrder}_${dict.order}_${dict.title}">${dictListOrder}.${dict.order}.&nbsp;${dict.title}</a>
</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33%;">
<col style="width: 33%;">
<col style="width: 33%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Code</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody><%for(dataDict in dict.dataDictList){%>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">${dataDict.value}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${dataDict.type}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">${dataDict.desc}</p></td>
</tr>
<%}%>
</tbody>
</table>
</div>
<%}%>
</div>
</div>
<%}%>
<footer class="page-footer"><span class="copyright">Generated by smart-doc at ${createTime}</span><span
class="footer-modification">Suggestions,contact,support and error reporting on<a
href="https://gitee.com/sunyurepository/smart-doc" target="_blank">&nbsp;Gitee</a>&nbsp;or<a
href="https://github.com/shalousun/smart-doc" target="_blank">&nbsp;Github</a></span></footer>
</div>
<script> $(function () {
var Accordion = function (el, multiple) {
this.el = el || {};
this.multiple = multiple || false;
var links = this.el.find('.dd');
links.on('click', {el: this.el, multiple: this.multiple}, this.dropdown);
};
Accordion.prototype.dropdown = function (e) {
var $el = e.data.el;
$this = $(this), $next = $this.next();
$next.slideToggle();
$this.parent().toggleClass('open');
if (!e.data.multiple) {
$el.find('.submenu').not($next).slideUp("20").parent().removeClass('open');
}
};
new Accordion($('#accordion'), false);
});</script>
</body>
</html>