Smart-doc 仅需要注释即可全自动生成开发文档 Springboot 开发必备 代替Swagger
2023-05-30
阅读 {{counts.readCount}}
评论 {{counts.commentCount}}
## 前言
如题，之前用过swagger，感觉替代postman很合适，但当成文档用就差口气。文档用过knife4j，apidoc，都属于还行，但总感觉各有优缺点，还是不是最贴近需求。
一番搜索后发现smart-doc最符合需求，即：最小的代码侵入性、与代码实时同步更新、前期工作量最低、可单独生成单独部署等等
<br>
## 折腾
**先放地址**
[smart-doc 官方文档](https://smart-doc-group.github.io/#/zh-cn/)
[smart-doc github](https://github.com/smart-doc-group/smart-doc)
<br>
**官方效果图**
<br>
**具体代码实现**
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>
```
<br>
在`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
}
]
}
```
<br>
此时更新maven，就可以看到生成html文档的方法：
点击就会在`src/main/resources/static`下生成`doc`目录，项目启动就可以直接访问 `http://localhost:port/projectname/doc/index.html`
如果是发布到线上则可以访问
`http://domain:port/projectname/doc/index.html`
注意：只有这种方法生成出来的domain和port才是完全一致，可以免跨域直接在线调用接口，如果doc和项目分开放，就需要配置跨域！
<br>
在`Controller`中添加配置
首先在Controller的最上方添加备注 具体如下
```java
/**
* 临时测试接口
* @author zzzmh
* @date 2023/4/11 16:08
* @email admin@zzzmh.cn
*/
@RequestMapping("/test")
@RestController
public class TestController
```
<br>
然后在具体方法上添加备注
```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));
}
```
<br>
生成到html后的效果 (传入参数也可以是formData)
<br>
如果传入参数是一个`@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;
}
```
效果图：
<br>
再啰嗦一遍
全部完成后在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)
沪公网安备31010602005070号