Spring-Boot集成smartdoc生成api文档

jiezi

5 年前

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

注意： 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 文档。
开放文档数据，可自由实现接入文档管理系统。

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

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.7.0</version>
    <scope>test</scope>
</dependency>

新建一个对象：

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 充当原创。

Spring-Boot集成smartdoc生成api文档

smart-doc 功能

在 Spring Boot 项目中集成 Smart-doc

用户信息操作接口

添加用户