接口文档生成工具smart-doc

本当迷

2023 年 03 月 03 日

75 次浏览

2 条评论

2029字数

java

## 一简介：

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. 完善项目中的注释**

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

![](https://www.bdmcom.cn/usr/uploads/2023/03/430376467.png)

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

![](https://www.bdmcom.cn/usr/uploads/2023/03/3586697685.png)

> 注意：我们项目中的类、方法、属性，都必须使用文档注释！
>
> 作为开发人员，一定要养成规范编写注释的好习惯。

**2. smart-doc的配置信息**

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

```json
{
  "serverUrl": "http://localhost:8080",
  "outPath": "src/main/resources/static/doc",
  "isStrict": false,
  "#####": "allInOne:true  此参数表示记录文档变更的记录",
  "createDebugPage": false,
  "packageFilters": "com.bdm.smartdocdemo.controller.*",
  "style":"xt256",
  "showAuthor":true,
  "inlineEnum": true,
  "revisionLogs": [{
    "version": "1.0",
    "revisionTime": "2020-12-31 10:30",
    "status": "创建",
    "author": "本当迷",
    "remarks": "学生管理系统"
  }],
  "appToken": "04e63b7d747a420fa844b6bf2b6f5682",
  "openUrl": "http://192.168.231.129:7700/api",
  "debugEnvName":"doc", 
  "replace": true,
  "debugEnvUrl":"http://127.0.0.1:8080"
}
```

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

https://smart-doc-group.github.io/#/zh-cn/diy/config

**3. 配置smart-doc插件**

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

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

![](https://www.bdmcom.cn/usr/uploads/2023/03/293523430.png)

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

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

![](https://www.bdmcom.cn/usr/uploads/2023/03/2113178843.png)

浏览器打开api.html

![](https://www.bdmcom.cn/usr/uploads/2023/03/638142404.png)

最后修改：2023 年 03 月 03 日