Smart-Doc文档生成
Smart-Doc文档生成
本教程将带你快速了解 Smart-doc 的基本用法,帮助你轻松生成漂亮的 API 文档。
什么是 smart-doc?
smart-doc 是一款同时支持 JAVA RESTful API 和 Apache Dubbo RPC 接口文档生成的工具。完全基于注释生成文档,做到零侵入。
安装和配置
首先,我们需要在项目中引入 Smart-doc。可以通过 Maven 或 Gradle 来添加依赖。以Maven为例
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>${smart.doc.version}</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>${project.name}</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库加载不到导致报错,这时请使用excludes排除掉-->
<excludes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<!--<exclude>com.alibaba:fastjson</exclude>-->
</excludes>
<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有,因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效率,因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为:groupId:artifactId;参考如下-->
<!--也可以支持正则式如:com.alibaba:.* -->
<!--<include>com.alibaba:fastjson</include>-->
</includes>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
<!--<phase>compile</phase>-->
<goals>
<!--smart-doc提供了html、openapi、markdown等goal,可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
完成依赖引入后,我们需要进行一些配置。在${basedir}/src/main/resources/smart-doc.json
中添加以下配置:
{
"outPath": "target/docs",
"serverUrl": "http://127.0.0.1:9981",
"sortByTitle": true,
"allInOne": true,
"style": "xt256",
"showAuthor": false,
"createDebugPage": true,
"replace": true
}
编写 API
/**
* Test服务
*
* @author devcxl
*/
@RestController
@RequestMapping("/test")
public class TestController {
@Resource
private TestService TestService;
/**
* Test签名
*
* @description 接口详情:xxxxxxxxxxxxxxx
* @param address 地址
* @param projectId 项目ID
* @param contract 合约
* @return
*/
@PostMapping("/sign")
Result<String> sign(@RequestParam String address, @RequestParam Integer projectId, @RequestParam String contract) {
return TestService.sign(address, projectId, contract);
}
}
生成文档
当你完成 API 接口的编写后,可以使用 Smart-doc 来生成文档。在终端中执行以下命令:
mvn smart-doc:html
这将生成 HTML 格式的 API 文档,保存在target/docs
目录下。你也可以根据需要生成其他格式的文档,如 Markdown、pdf 等。
结合 Torna 使用
如果想要结合 Torna 使用,需要在smart-doc.json
中添加以下配置
{
"appToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"openUrl": " http://your-torna-domain/api",
"debugEnvName": "测试环境",
"debugEnvUrl": "https://your-test-domain"
}
当你完成以上配置后,在终端中执行以下命令:
mvn smart-doc:torna-rest
这将生成文档并通过 openUrl 和 appToken 上传到 Torna 服务器。