一. 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文件，在该文件中输入如下内容：

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

3. 配置smart-doc插件

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

<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 测试接口

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