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 服务器。

参考