Java接口文档生成工具-smart-doc

Java接口文档生成工具-`smart-doc`

写接口文档的烦恼

通常在web开发中我们写完接口需要向前端开发人员提供接口文档，前端开发人员根据我们提供的文档做接口开发。而对于大多数开发人员来说，写接口文档真的太痛苦了。往往在项目开发中我们需要花费大量的时间去维护这份接口文档，特别有时候接口做了调整而自己忘记修改文档，造成对接开发过程效率低下事常有发生。

Swagger

对于上面的情况，我找到业界常用的工具Swagger，通过它可以自动生成接口文档，但是使用Swagger需要在代码中添加许多注解，因为需要生成文档我不得不在代码中增加需要为了生成文档的代码，这个对于代码的入侵性实在是太强了。

`smart-doc`

查找过很多资料之后，还真就找到一个对代码零侵入的神器Smart-doc。先给出github地址：https://github.com/smart-doc-group/smart-doc。

先对Swagger来说，Smart-doc几乎没有侵入。写代码时你只需要写应有的java-doc注释，然后使用maven插件就能生成对应的文档。

如何使用

在项目中的pom文件中添加smart-doc插件

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</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>

增加配置文件，也就是上面插件中<configFile>./src/main/resources/smart-doc.json</configFile>配置文件。

{
   "outPath": "./doc" 
}

上面就是smart-doc.json的最小配置内容，也就是说你只用配置上面的内容就已经可以自动生成文档了。

使用maven命令生成文档。

只需要一条命令，mvn -Dfile.encoding=UTF-8 smart-doc:html 就能生成文档。文档生成后就在smart-doc.json配置文件中指定的目录。

示例代码

API接口代码:

@RestController
@RequestMapping("test")
@CrossOrigin
public class TestController {

    /**
     * 查询用户
     * @param userName 用户名称
     * @return 用户信息
     */
    @GetMapping("get_user")
    public BaseResp<UserInfo> queryUser(String userName){
        UserInfo user = new UserInfo();
        user.setUserName(userName);
        user.setAge(18);
        return BaseResp.ok(user);
    }
}

通用响应体：

@Data
public class BaseResp<T> {
    /**
     * 响应码
     */
    private String code;
    /**
     * 响应消息
     */
    private String msg;
    /**
     * 响应数据
     */
    private T data;

    public static <T> BaseResp<T> ok(T data){
        BaseResp<T> resp = new BaseResp<>();
        resp.setCode("2000");
        resp.setMsg("请求成功");
        resp.setData(data);
        return resp;
    }
}

UserInfo响应结果：

@Data
public class UserInfo {
    /**
     * 用户名称
     */
    private String userName;
    /**
     * 用户年龄
     */
    private Integer age;
}

从上面的实例代码中可以看出，Smart-doc生成的文档并没有对源码有任何侵入性。

资料扩展

当然Smart-doc还有很多配置项可以配置，具体使用方式可以参考官网的使用文档，整体上来说个人感觉还是比较简单，同时也能满足我的需求。

官方使用手册：https://smart-doc-group.github.io/#/zh-cn/start/quickstart

原文始发于微信公众号（一只菜鸟程序员）：Java接口文档生成工具-smart-doc

文章由极客之音整理，本文链接：https://www.bmabk.com/index.php/post/72918.html

Java接口文档生成工具-smart-doc