Smart-doc教程（Swagger的无侵入式替代方案）

Smart-doc教程

一、基础入门：

• 首先第一个要推荐的绝对是官方wiki文档，因为smart-doc的更新速度很快，网上的教程或者介绍大多是2.0版本之前的，而且因为比较新这个工具，所以资源也比较少，因此以下的学习分享基本上都来自文档和官方QQ群大佬的指导。

• 官方Gitee wiki

---

二、开始使用

1. 使用前需要了解一下javadoc的一个基本写法

 /**
     * 重置工程下指定用户的所有节点状态
     * @param projectId 小程序用户OpenId
     * @param openId 要重置打卡状态的工程Id
     * @return
     * @throws IOException
     */

• 基本写法就长这样
• 第一行表示对改方法的一个介绍
• @param则是传入参数的一个解释说明
• @return 则是返回值的说明不过一般来说可以不用写
• @throws 则是抛出的异常

---

• 还有就是在类处要加上这个类的作用说明以及作者是谁，还可以加个创建时间这样会比较规范：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qJ89WjRT-1610896158822)(https://i.bmp.ovh/imgs/2020/12/ea2601b514fa878f.png)]

2.在pom中添加安装smart-doc插件（官方强烈推荐使用插件+json配置文件的方式构建api文档而不是编写单元测试的方式）

• 这里举个例子 详细的配置文件和可配置参数可以去看官方文档

   //当前最新版本为2.0.1 实测+官方回答是存在bug的，所以需要等后续版本修复，已提issue
   //还有就是这里提一下 最好是去github把官方的smart-doc源码clone下来本地install一下以保证版本是最新的
    <plugin>
        <groupId>com.github.shalousun</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>2.0.1</version>
        <configuration>
            <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
            <configFile>./src/main/resources/smart-doc.json</configFile>
        </configuration>
    </plugin>

• 添加并编写配置文件 smart-doc.json

{
  "serverUrl": "http://localhost:8086",
  "isStrict": false,
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "coverOld": true,
  "createDebugPage": true, //启用生成debug
  "md5EncryptedHtmlName": false,
  "projectName": "和帆打卡活动"
}

• 添加完插件和配置文件后重新加载一下maven，就会看到plugins插件处多出了smart-doc的选项
• [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-HTVttd1m-1610896158830)(https://i.bmp.ovh/imgs/2020/12/cad1f61596bc693d.png)]

---

3. 编写javadoc注释

• 这里建议查看官方wiki进行学习，里面有示例和一些自定义tag的用法说明
• wiki javadoc的使用

4. 运行smart-doc插件

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ofank7nW-1610896158834)(https://i.bmp.ovh/imgs/2020/12/3f9de63d16302662.png)]

这里根据需要生成的api文档类型选择点击生成就好

5. 使用debug调试模式

划重点！！！ 划重点！！！

---

2.0.0之后smart-doc支持在线调试（跟swagger一样，虽然比起swaggerUI界面比较简洁，不过这都不重要啦 主要是无侵入式的生成可在线调试的api文档这点是最香的）

设置方式特别简单，只需要改一下配置文件就好，参考我上面的配置文件

在线debug调试参考文档

---

五、调试界面预览

• 请求参数
  [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-349O7oM3-1610896158838)(https://i.bmp.ovh/imgs/2020/12/a19ca00cbc22294d.png)]
• 请求失败演示
  [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-5HuCq1Z0-1610896158841)(https://i.bmp.ovh/imgs/2020/12/87d818426617424e.png)]
• 请求成功演示
  [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-DMwwwg3q-1610896158844)(https://i.bmp.ovh/imgs/2020/12/bbb4a2630911eaee.png)]