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

清疚 2024-03-27 13:37 74阅读 0赞

## 一. 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][https_smart-doc-group.github.io_zh-cn_id_smart-doc]

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

## 二. SpringBoot项目集成smart-doc ##

### 1. 完善项目中的注释 ###

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

![c2ae8dfed6f84109bf803e96fa2ad3c9.png][]

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

![bd2e67f4cfa8407ea4903b4dbde33b68.png][]

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

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

### 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各种格式的文档，如下图所示：

![2ebc43bee83443bc926d1ca8b007e48f.png][]

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

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

![cc18a3275a2447d38d3b0de364f5a62a.png][]

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

### 5. 接口文档界面效果 ###

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

![f02a245fc4b7474eb1e04866b7d12ccc.png][]

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

## 三. 接口测试 ##

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

#### 1.1 生成文档 ####

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

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

![ded49a0f13224f54a7ae77e56413f801.png][]

#### 1.2 运行测试 ####

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

![0f6c125da4b449baa08b933179065f0f.png][]

### 2. 导入ApiPost进行测试 ###

#### 2.1 生成postman格式文档 ####

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

![82712a21ada7483590181a8fa563c678.png][]

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

![afc8ab100a6346f98651cbd636e30db7.png][]

#### 2.2 导入文档 ####

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

![efe7eabd2c964f159f2167a8ef5b1ae4.png][]

![47749823d85d4e0b8bc553283ed60626.png][]

#### 2.3 测试接口 ####

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

![39d7dec4709148d691d9dc01f2867528.png][]

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

[https_smart-doc-group.github.io_zh-cn_id_smart-doc]: https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc
[c2ae8dfed6f84109bf803e96fa2ad3c9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/a14870d0bff14fb4858c183231998392.png
[bd2e67f4cfa8407ea4903b4dbde33b68.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/33d7b583d3e0465aaa3838fb5538919c.png
[2ebc43bee83443bc926d1ca8b007e48f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/58d7b374bfc34be8aa4f42389bee54cc.png
[cc18a3275a2447d38d3b0de364f5a62a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/0d6aabe455724b40848fa71b392978ee.png
[f02a245fc4b7474eb1e04866b7d12ccc.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/d599d309ae3b4444a228b8526cdf5c53.png
[ded49a0f13224f54a7ae77e56413f801.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/80f26ecb214f404aa124f563cf64cdd6.png
[0f6c125da4b449baa08b933179065f0f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/396fed7d44d342a0876649d8ba2c1dbf.png
[82712a21ada7483590181a8fa563c678.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/c630f3afc2994e15a71e4decbd8cee9d.png
[afc8ab100a6346f98651cbd636e30db7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/88ec567ed6c84e1f9165c257c59aa088.png
[efe7eabd2c964f159f2167a8ef5b1ae4.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/3f45fdb6ce3247b7a6c01146437df869.png
[47749823d85d4e0b8bc553283ed60626.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/c3ab21e7c9df4c11810a5d7f4c590137.png
[39d7dec4709148d691d9dc01f2867528.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/27/9c3f9c198d714abaaa38f4e758d116dd.png