比swagger2更好用的文档工具smart-doc，你确定不来学习一下？

一. smart-doc简介

smart-doc是一款接口文档生成工具，它完全是根据接口源码进行分析生成接口文档，不会使用任何注解侵入业务代码中。这一点与swagger完全不同，swagger侵入性强，需要编写大量注解。

在Java项目中，我们只需要按照java-doc的标准编写注释，就能生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+格式的文档。

smart-doc帮助文档：https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc

壹哥"墙裂"建议：作为技术人员，一定要学会通过帮助文档学习各种技术哦

二. SpringBoot项目集成smart-doc

1. 完善项目中的注释

给实体类添加相关的注释，如下图所示：

我们在控制器上也添加应有的注释。

注意：我们项目中的类、方法、属性，都必须使用文档注释！

作为开发人员，一定要养成规范编写注释的好习惯。

2. smart-doc的配置信息

接着我们要在resource目录下新建一个smart-doc.json文件，在该文件中输入如下内容：

{
  "serverUrl": "http://localhost:8080",   // 服务器地址，非必须
  "pathPrefix": "",                       // 上下文路径
  "allInOne": true,                       // 是否将文档合并到一个文件中，一般推荐为true
  "outPath": "D://md2",                   // 指定文档的输出路径
  "style": "xt256",                       // 基于highlight.js的代码高亮设置
  "createDebugPage": false,               // 创建一个可调试接口的文档页面
  "revisionLogs": [                       // 文档变更记录，非必须
    {
      "version": "1.0",                   // 文档版本号
      "revisionTime": "2023-01-31 10:30", // 文档修订时间
      "status": "创建",                   // 变更操作状态，一般为：创建、更新等
      "author": "renr",                   // 文档变更作者
      "remarks": "员工管理系统"            // 变更描述
    }
  ]
}

smart-doc的配置项很多，其他各种配置可参考上文提到的帮助文档进行查看。

3. 配置smart-doc插件

接着我们要在pom.xml文件的plugins标签中，增加如下内容：

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.6.4</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>员工系统接口文档</projectName>
    </configuration>
</plugin>

<configFile>中指定需要调用的smart-doc配置文件的路径。

4. 生成文档

在idea中，我们可以直接通过插件生成smart各种格式的文档，如下图所示：

在本例中，我们双击smart-doc:html就可以生成html格式的接口文档。

生成文档后，所在目录中的内容如下：

配置"allInOne": true后，生成的文档中只会包含一个index.html文件。如果设置为false，生成的接口文档会包括api.html、dict.html和error.html多个文件，大家可以自行测试。

5. 接口文档界面效果

最后我们双击index.html，就可以查看生成的接口文档效果了。

大家可以根据上文的smart-doc配置，找找每个配置在接口文档中对应显示的内容。

三. 接口测试

1. 配置调试页面进行测试

1.1 生成文档

根据上文的配置，默认情况下，仅是生成接口文档，配置"createDebugPage": true，双击插件的smart-doc:html选项，即可生成带接口调用功能的接口文档。怎么样，这个功能是不是相当强大？

生成带调试功能的接口文件，如下所示：

1.2 运行测试

此时双击debug-all.html，运行测试文档后，页面如下：

2. 导入ApiPost进行测试

2.1 生成postman格式文档

接着我们再双击smart-doc:postman，生成一个postman格式的文档：

生成的postman格式文档如下所示：

2.2 导入文档

我们还可以在ApiPost中导入该文档，其步骤如下：

2.3 测试接口

导入后，我们可以切换到导入的项目，这样就可以进行接口测试了。

现在你知道smart-doc是怎么使用的了吗？如果你还有不明白的地方，可以在评论区或私信给壹哥留言。