Smart-doc 仅需要注释即可全自动生成开发文档 Springboot 开发必备代替Swagger

home 编辑时间 2023/05/30

![](/api/file/getImage?fileId=64759bfbda74050014001a65)

## 前言
如题，之前用过swagger，感觉替代postman很合适，但当成文档用就差口气。文档用过knife4j，apidoc，都属于还行，但总感觉各有优缺点，还是不是最贴近需求。
一番搜索后发现smart-doc最符合需求，即：最小的代码侵入性、与代码实时同步更新、前期工作量最低、可单独生成单独部署等等

## 折腾

**先放地址**
[smart-doc 官方文档](https://smart-doc-group.github.io/#/zh-cn/)
[smart-doc github](https://github.com/smart-doc-group/smart-doc)

**官方效果图**
![](/api/file/getImage?fileId=64759d98da74050014001a67)
![](/api/file/getImage?fileId=64759d98da74050014001a66)
![](/api/file/getImage?fileId=64759d98da74050014001a68)

**具体代码实现**
maven： pom.xml 添加依赖 并且在build中配置基本参数
```xml
<dependencies>
 <dependency>
 <groupId>com.github.shalousun</groupId>
 <artifactId>smart-doc</artifactId>
 <version>2.6.8</version>
 </dependency>
 <dependency>
 <groupId>com.github.shalousun</groupId>
 <artifactId>smart-doc-maven-plugin</artifactId>
 <version>2.6.8</version>
 </dependency>
</dependencies>
<build>
 <finalName>${project.artifactId}</finalName>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <configuration>
 <excludes>
 <exclude>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 </exclude>
 </excludes>
 </configuration>
 </plugin>
 <plugin>
 <groupId>com.github.shalousun</groupId>
 <artifactId>smart-doc-maven-plugin</artifactId>
 <version>2.6.8</version>
 <configuration>
 <configFile>./src/main/resources/smart-doc.json</configFile>
 <projectName>auction</projectName>
 </configuration>
 <executions>
 <execution>
 <phase>compile</phase>
 <goals>
 <goal>html</goal>
 </goals>
 </execution>
 </executions>
 </plugin>
 </plugins>
</build>
```

在`src/main/resources`目录下新增一个`smart-doc.json` 内容如下
具体意思参考文档: [https://smart-doc-group.github.io/#/zh-cn/diy/config](https://smart-doc-group.github.io/#/zh-cn/diy/config)

```json
{
  "serverUrl": "https://api.xxx.com/",
  "allInOne": true,
  "allInOneDocFileName": "index.html",
  "createDebugPage": true,
  "outPath": "./src/main/resources/static/doc",
  "projectName": "smart-doc-test",
  "requestParamsTable": true,
  "responseParamsTable": true,
  "style": "atom-one-dark",
  "requestHeaders": [
    {
      "name": "token",
      "type": "string",
      "value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "required": true
    }
  ]
}
```

此时更新maven，就可以看到生成html文档的方法：
![](/api/file/getImage?fileId=64759ff1da74050014001a6e)
点击就会在`src/main/resources/static`下生成`doc`目录，项目启动就可以直接访问 `http://localhost:port/projectname/doc/index.html`
如果是发布到线上则可以访问
`http://domain:port/projectname/doc/index.html`
注意：只有这种方法生成出来的domain和port才是完全一致，可以免跨域直接在线调用接口，如果doc和项目分开放，就需要配置跨域！

在`Controller`中添加配置
首先在Controller的最上方添加备注 具体如下
```java
/**
 * 临时测试接口
 * @author zzzmh
 * @date 2023/4/11 16:08
 * @email admin@zzzmh.cn
 */
@RequestMapping("/test")
@RestController
public class TestController
```

然后在具体方法上添加备注
```java
/**
 * 一个测试接口
 * @param test 测试参数|abcd1234
 * @return
 * @response {"code":0,"message":"success","data":{"test":"abcd1234"}}
 */
@PostMapping("/test")
public Result test(@RequestParam String test) {
 return Result.ok(JSONObject.of("test", test));
}
```

生成到html后的效果 (传入参数也可以是formData)
![](/api/file/getImage?fileId=6475aca1da74050014001a9d)
![](/api/file/getImage?fileId=6475acbfda74050014001a9e)

如果传入参数是一个`@RequestBody` 就这样写
其中
`@mock` 是给参数一个例子
`@required` 是此项为必填项
```java
/**
 * 翻页表单
 * @author zzzmh
 * @date 2023/4/11 10:43
 * @email admin@zzzmh.cn
 */
@Data
public class PageForm {

/**
     * 个数
     * @mock 10
     * @required
     */
    @NotNull
    private Long size ;

/**
     * 页码
     * @mock 1
     * @required
     */
    @NotNull
    private Long current;
}
```

效果图：
![](/api/file/getImage?fileId=6475ad96da74050014001a9f)

再啰嗦一遍
全部完成后在maven中执行 `smart-doc:html`
就会在`resources/static`下生成`doc`目录
访问项目路径 + `/doc/index.html` 既可访问最终效果
且这样访问项目的domain和port都是相同的，就可以直接调用接口
如果你把项目和doc分开放，就需要配置跨域才能在线调接口。

## END
基本就是这些
可以看出前期代码量非常小，且都是注释，对项目0入侵
生成后的文档对前端界面友好，且可以直接在线调用

更多内容请参考官方文档
[smart-doc 官方文档](https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc)

送人玫瑰,手留余香