smart-doc详细完整使用教程

本教程使用IDEA+官方示例生成文档的过程，目的是知道这个smart-doc怎样生成文档，然后再根据自己的需要进行调整接口注释。

一、对学习smart-doc有用的网址

1、官方参考文档：Document (smart-doc-group.github.io)

 2、smart-doc源码：smart-doc: smart-doc是一款同时支持java restful api和apache dubbo rpc接口文档生成的工具。完全基于注释生成文档，做到零侵入。 (gitee.com)

3、smart-doc官方示例：smart-doc-example-cn: smart-doc demo，仅为github的同步仓库，pr请前往github (gitee.com)

 二、下载并导入smart-doc官方示例

下载后会发现该项目使用的是JAVA17，用JAVA8不行，JAVA21也是不行，必须要用JAVA17

如果没有JAVA17 ，到官方下载一个免安装的，也不需要配置环境变量，引入到IDEA即可。

JAVA17官方下载JAVA17官方下载

解压到你的java目录

在IDEA的File --> Project Structure -->  Platform Settings --> SDKs，引入JAVA17

 

引入后，会多了17这个版本

然后点击Project，在Project SDK中改成17版本

点击OK

 三、启动项目

点击右边的compile命令，验证一下项目，同时下载相关依赖

如果出现BUILD SUCCESS证明编译通过

右键SpringBootMainApplication，运行项目

如果出现Started SpringBootMainApplication in xxx seconds (process running for xxx)证明可以启动成功。

四、生成文档

依次点击smart-doc-example-cn、Plugins、smart-doc，最后双击smart-doc:html，就会生成文档

如果出现BUILD SUCCESS，那就证明生成成功，并且在输出信息也能找到生成的位置

打开该目录，能看到生成的文档，并打开 html文件

这些文档就是根据项目的注释生成的

五、文档分析

1、文档对应关系

打开项目中的

UserController

package com.power.doc.controller;

import com.power.doc.entity.*;
import com.power.doc.entity.page.Page;
import org.springframework.web.bind.annotation.*;

/**
 * 用户信息操作接口
 * @author yu 2018/8/4.
 */

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/add")
    public ResultUtil<User> addUser(@RequestBody SimpleUser user){
        return null;
    }

    /**
     * 更新用户
     * @param user @mock  {"address":"成都市","sex":1,"age":16,"name":"smart-doc","extand""{"version":1.0,"versionList":["1.2.0","1.5.6"]}}
     * @return
     */
    @PutMapping("/update")
    public User updateUser(@RequestBody SimpleUser user){
        return null;
    }
}

再在页面上搜索/add，定位到用户信息操作文档

 都能找到对应，并且文档会深入参数对象的注释把它显示在上面，我们根据自己的需要和官方的文档写法进行文档补充，就能生成自己的文档。

2、smart-doc插件的使用

打开pom.xml，能看到引入了smart-doc-maven-plugin，所以我们能在IDEA中使用该插件生成文档。所以当我们需要对我们自己的项目生成文档，并不是引入依赖，而是添加插件。

上面配置中有一个smart-doc.json配置

<configFile>./src/main/resources/smart-doc.json</configFile>

在项目中打开这个配置

可以看到有很多配置，其中outPath是输出位置

官方给出的最小化配置也只需一个outPath就可以。

还有一个要注意配置的地方<includes>

include是要生成文档的包名，smart-doc只会读取这里配置的包。

假如你的项目的包名是com.demo.xxx，那你就需要添加

<include>com.demo:.*</include>

六、总结

把smart-doc引入我们的项目的步骤：

1、在pom.xml下添加smart-doc插件配置

2、在项目的resources下添加smart-doc.json配置，smart-doc.json最小化配置是一个outPath

3、在我们的Controller中添加相关注释，相关类也添加注释

4、使用maven命令生成文档，官方给出的是

生成html：
mvn -Dfile.encoding=UTF-8 smart-doc:html

生成markdown：
mvn -Dfile.encoding=UTF-8 smart-doc:markdown

生成torna：
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

也可以使用IDEA的快捷操作，双击smart-doc:html生成