好用的文档工具👉smart-doc
<h2 id="好用的文档工具smart-doc">好用的文档工具👉smart-doc</h2><blockquote>
<p>转载请注明出处https://www.cnblogs.com/funnyzpc/p/18932813</p>
</blockquote>
<p>smart-doc不得不说是一款非常好用的文档工具，尤其是它几乎不与项目耦合的特性十分值得所有java开发人员日常使用它~</p>
<h3 id="之前及现在用的">之前及现在用的</h3>
<p>我从事开发以来，用过形形色色各式各样的文档工具,比如一开始的用</p>
<h4 id="01-word或excel">01. word或excel</h4>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701110701736-1531105216.png"></p>
<p>这种文档十分依赖于开发人员同步维护，另外office与代码是两套东西，耗时耗力且很容易<br>
由于疏忽忘记维护，导致版本版本不一致的问题~</p>
<h4 id="02-showdoc">02. showdoc</h4>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701110810479-1791284256.png"></p>
<p>这东西看起来比较美观,非常适合外部人员接入之使用，当然缺点也很明显：</p>
<ul>
<li>公开文档安全及私密性就差很多</li>
<li>也同样存在手动编写的问题，需要跟随代码同步维护</li>
<li>使用范围比较窄，虽方便接入人员用，测试及开发自测仍旧比较麻烦</li>
<li>导入导出似乎受限制，不知道现在有没改善😂</li>
</ul>
<h4 id="03-swagger">03. swagger</h4>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701110840643-881261042.png"></p>
<p>后来有了有了 <code>swagger</code>,一开始觉得这东西蛮不错的，主要体现在：</p>
<ul>
<li>不需要再写word或excel</li>
<li>定义文档接口的方式更贴合传统编码的方式</li>
<li>文档可生成在线网页doc的方式也可以通过跑代码生成<code>adoc</code>文件+<code>asciidoctor工具</code>生成单<code>html</code>文档，这非常利于文档分发</li>
</ul>
<p>东西虽好，但是缺点也是十分明显的：</p>
<ul>
<li>代码耦合性太强了，<code>swagger</code>依赖必须与代码一起部署（包括生产）</li>
<li>在线文档十分便捷，但是由于 <code>swagger</code> 可能的漏洞的存在，增加了系统风险的可能性（这个本人碰到过）</li>
<li>能生成实用的``html文档，可似乎缺少了供测试使用的 <code>jmeter</code> 及 <code>postman</code>文档，测试人员依然需要手动构建测试接口</li>
<li>特别需要注意的是<code>swagger</code> <code>v2</code>及之后似乎缺少了<code>html</code>文档的生成途径（文档工具不能越做越返祖啊...）😂</li>
<li><code>swagger</code> 文档不论是在线的还是离线的文档 对于复杂的 <code>json</code> 需要逐级便利 (如果能平铺为一个table就好了) 😓</li>
</ul>
<h4 id="04-smart-doc">04. smart-doc</h4>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111047818-2115289214.png"></p>
<p>这个文档工具在目前我所经手的项目中广泛之使用，如图，需要的功能基本都有了🥰</p>
<h3 id="smart-doc-有啥优点">smart-doc 有啥优点</h3>
<ul>
<li>由于仅有 <code>plugin</code> 及一个<code>json</code>配置,无任何 <code>ApiModelProperty</code> 、 <code>ApiModel</code> 及 <code>Schema</code> 侵入性注解代码</li>
<li>可以生成诸如 <code>html</code>（单文件需要先走adoc后转html）、<code>openapi</code>、<code>postman</code>、<code>jmeter</code>、<code>word</code> 等主流且前端用也可后端测试用之文档</li>
<li>文档定义更简单，仅需有限的注解及 <code>Jakarta</code> 相关注解配合使用即可, 其他扩展文档见 smart-doc</li>
<li></li>
</ul>
<h3 id="如何使用">如何使用</h3>
<ul>
<li>在项目中添加 <code>plugin</code> 配置，这里仅以 <code>maven</code> 项目实例</li>
</ul>
<pre><code class="language-xml"><!--文档工具-->
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<!--配置文件位置-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--<projectName>${application.name}</projectName>-->
<!--<configFile>${application.name}</configFile>-->
</configuration>
<!--项目编译时执行生成html不需要可以去掉executions标签-->
<executions>
<execution>
<!--打包的时候构建文档(install package)-->
<phase>package</phase>
<goals>
<!--adoc文档，后续用asciidoc生成html单文档-->
<goal>adoc</goal>
<!--构建文档类型 -->
<!--api只构建html文档-->
<!--<goal>html</goal>-->
<!--统一接口只构建adoc文档-->
<!--<goal>rpc-adoc</goal>-->
</goals>
</execution>
</executions>
</plugin>
<!--文档工具:用于将smart-doc生成的adoc文件转换为html文档-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.8</version>
<configuration>
<!--预构建文档目录-->
<sourceDirectory>./adoc</sourceDirectory>
<!--文档输出目录-->
<outputDirectory>./doc</outputDirectory>
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--菜单栏在左边-->
<toc>left</toc>
<!--多标题排列-->
<toclevels>3</toclevels>
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- 文档工具结束-->
</code></pre>
<p><code>plugin</code>在多模块项目中表现为:</p>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111213657-2122761807.png"></p>
<ul>
<li>在项目中定义 <code>smart-doc.json</code> 配置文件,一般在 <code>resources</code> 目录下</li>
</ul>
<pre><code class="language-json">{
"outPath":"adoc",
"allInOne":true,
"allInOneDocFileName":"mee_admin-1.0.1",
"projectName":"mee_admin",
"createDebugPage":true,
"revisionLogs":[
{
"version":"2025-06-26",
"author":"shadow",
"revisionTime":"2025-06-26 19:28:18",
"status":"1.0.1",
"remarks":"接口及文档优化"
}
]
}
</code></pre>
<p>这个 <code>smart-doc.json</code> 在 <code>plugin</code> 中有引用，相对地址不要弄错了</p>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111315341-676765773.png"></p>
<ul>
<li>在 <code>idea</code> 的 <code>maven</code> 面板依次操作=>生成单html文档文件</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111327041-397027703.png"></p>
<h3 id="使用技巧及注意事项">使用技巧及注意事项</h3>
<ul>
<li>字段的注释不可以含有竖杠(eg: <code>|</code> ), 可能造成文档出现偏移</li>
</ul>
<pre><code class="language-java">// eg:
/**
* 菜单类型(1.目录 | 2.菜单 | 3.按钮）
*/
private Integer type;
</code></pre>
<ul>
<li>入口注释字段 <code>@param</code> 的值不可为空, 可导致无法生成文档</li>
</ul>
<pre><code class="language-java"> // eg:
/**
* 系统::文件管理::删除
* @param status 状态
* @param
*/
@RequiresPermissions("sys:sys_file:delete")
@DeleteMapping("/delete")
@ResponseBody
public MeeResult<Integer> deleteById(@RequestParam(required = true) String id,@RequestParam(required = true) String status){
return sysFileService.deleteById(id,status);
}
</code></pre>
<ul>
<li><code>smart-doc</code> 强烈推荐使用 <code>3.1.x</code> 以上的版本,若使用 <code>3.1.x</code> 以下版本 多个 <code>@RequestHeader</code> 时生成的文档会出现行偏移</li>
</ul>
<pre><code class="language-java">// eg:
@RequiresPermissions("sys:sys_file:delete")
@DeleteMapping("/delete")
@ResponseBody
public MeeResult<Integer> deleteById(@RequestHeader String aa ,@RequestHeader String status){
return sysFileService.deleteById(id,status);
}
</code></pre>
<ul>
<li>一定要注意<code>xml</code>配置的目录或文件的位置</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111356715-959022156.png"><br>
<img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111436853-1362502390.png"></p>
<ul>
<li>
<p>生成的<code>jmeter</code>文档不可避免的会出现打不开的问题，一般来是注释含有<br> 或者 数字或布尔默认值问题,此类问题建议按提示的行数 修改 <code>jmx</code> 内对应的行即可</p>
</li>
<li>
<p>具体配置参见smart-doc官方文档</p>
</li>
</ul>
<h3 id="文档生成效果">文档生成效果</h3>
<ul>
<li>单 <code>html</code> 文档</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111501696-1189864290.png"></p>
<ul>
<li><code>jmeter</code> 文档</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111515220-1321245680.png"></p>
<ul>
<li><code>word</code> 文档</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/1161789/202507/1161789-20250701111535821-376014003.png"></p>
</div>
<div id="MySignature" role="contentinfo">
funnyzpc@gmail.com<br><br>
来源：https://www.cnblogs.com/funnyzpc/p/18932813
頁:
[1]