Spring Boot集成smart-doc生成api文档

smart-doc是一个java restful api文档生成工具，smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照java标准注释的写，smart-doc就能帮你生成一个简易明了的markdown或是一个像GitBook样式的静态html文档。
下面将介绍如何在Spring Boot项目中集成smart-doc生成一个简明的api文档。

注意： smart-doc已经被开源中国收录，并且开始被国内很多开发者使用到自己项目中快速生成接口文档。

smart-doc功能

• 零注解、零学习成本、只需要写标准java注释。
• 基于源代码接口定义自动推导，强大的返回结构推导。
• 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
• 支持Callable,Future,CompletableFuture等异步接口返回的推导。
• 支持JavaBean上的JSR303参数校验规范。
• 对json请求参数的接口能够自动生成模拟json参数。
• 对一些常用字段定义能够生成有效的模拟值。
• 支持生成json返回值示例。
• 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
• 支持生成多种格式文档：Markdown、HTML5、Asciidoctor。
• 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
• 开放文档数据，可自由实现接入文档管理系统。

  在Spring Boot项目中集成Smart-doc

  添加smart-doc依赖，注意打包后不需要将smart-doc打入最终的产品包，因此我推荐只用test级别就可以了。

    com.github.shalousun
    smart-doc
    1.7.0
    test

新建一个对象：

public class User {

    /**
     * 用户名
     */
    private String userName;

    /**
     * 昵称
     */
    private String nickName;

    /**
     * 用户地址
     */
    private String userAddress;

    /**
     * 用户年龄
     */
    private int userAge;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 创建时间
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * 固定电话
     */
    private String telephone;
    //省略get set
}

下面来新建一个UserController，然后将User作为Controller的请求参数和响应实体测试下smart-doc是如何轻松完成文档生成的。

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

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

添加完成controller后，我们在项目中新建一个单元测试类用于跑文档。

public class ApiDocTest {

    /**
     * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //true会严格要求注释，推荐设置true
        config.setStrict(true);
        //true会将文档合并导出到一个markdown
        //config.setAllInOne(true);
        //生成html时加密文档名不暴露controller的名称
        config.setMd5EncryptedHtmlName(true);

        //指定文档输出路径
        //@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath("d:\\md");
        // @since 1.2,如果不配置该选项，则默认匹配全部的controller,
        // 如果需要配置有多个controller可以使用逗号隔开
        config.setPackageFilters("com.power.doc.controller");

        long start = System.currentTimeMillis();
        //获取接口数据后自行处理
        ApiDocBuilder.builderControllersApi(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

最后运行一下单元测试smart-doc即可生成markdown接口文档到指定的目录。

文档生成效果

用户信息操作接口

添加用户

URL: http://localhost:8080/user/add

Type: POST

Content-Type: application/json; charset=utf-8

Request-parameters:

Parameter	Type	Description	Required	Since
userName	string	用户名	false	-
nickName	string	昵称	false	-
userAddress	string	用户地址	false	-
userAge	int	用户年龄	false	-
phone	string	手机号	false	-
createTime	number	创建时间	false	-
ipv6	string	ipv6	false	-
telephone	string	固定电话	false	-

Request-example:

{
    "userName":"鹏飞.贺",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Response-fields:

Field	Type	Description	Since
userName	string	用户名	-
nickName	string	昵称	-
userAddress	string	用户地址	-
userAge	int	用户年龄	-
phone	string	手机号	-
createTime	number	创建时间	-
ipv6	string	ipv6	-
telephone	string	固定电话	-

Response-example:

{
    "userName":"鹏飞.贺",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

是不是比swagger简单很多呢，而且还完全不侵入代码，只需要写上标准的java doc注释。需要了解更多多情况请查看smart-doc项目，好用请记得点star哦。查看smart-doc项目

注意: 本文来自smart-doc原作者，您可以转载但请勿copy充当原创。