smart-doc功能使用介绍

原创
2018/10/22 23:33
阅读数 10.9W

smart-doc从2018年8月份底开源发布以来已经迭代了好几个版本。在这里非常感谢那些敢于用smart-doc去做尝试并积极提出建议的社区用户。因此决定在本博客中重要说明下smart-doc的功能,包括使用介绍。以减少后期用户使用中的一些疑惑。

一、简介

Smart-doc是一个完全无侵入的java Rest Api文档生成工具。让用户的代码保持整洁一直是Smart-doc的核心理念。smart-doc官方已经开发出了maven和gradle插件,因此我们不再推荐使用单元测试集成smart-doc。使用插件的文档效果更佳,集成到项目中也很方便。插件是为smart-doc赋能的。 因此本文当前看看就好,直接管官方仓库中的wiki文档介绍更全。

二、特殊功能介绍

2.1 JSR303支持

在当前许多的web项目中,我们都会直接使用JSR303来验证参数的合法性包括检验参数是否为必须参数等,smart-doc本身是为了帮助开发人员少去写一些无用的东西,整合标准的开发规范去帮助快速的生成文档。因此smart-doc自诞生那一刻起就已经支持JRS303验证规范。只要你写在字段上加了JSR303的验证注解或者是hibernate-validate的注解。smart-doc在输出请求参数文档时自动填写参数必填为true。请看代码片段:

public class Leader {
    /**
    * 姓名
    */
    @NotEmpty
    @Length(max = 5)
    private String name;
    /**
    * 生日
    */
    @NotBlank(message = "生日不能为空")
    @Pattern(regexp = "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", message = "出生日期格式不正确")
    private String birthday;
    /**
    * 年龄
    */
    @Min(value = 0)
    private Integer age;
    /**
    * 科目
    */
    @Valid
    @NotNull(message = "")
    private Subject subject;
}


参数请求文档:

Parameter Type Description Required
name string 姓名 true
birthday string 生日 true
age int 年龄 false
subject object 科目 true
└─subjectName string 科目名称 true

2.2 响应字段忽略

smart-doc能够自动解析fastjson和jackson的忽略字段注解正确输出到文档中。这个比较简单就不详细介绍了。

2.3 json数据响应字段别名识别

smart-doc能够解析fastjson的JSONField注解的name属性值和spring boot原始的jackson的JsonProperty注解value属性值来自动完成别名输出。做过json字段忽略都知道,这里简单介绍。

public class SubUser {

    /**
     * 用户名称
     */
    private String subUserName;

    /**
     *
     */
    private BigInteger numbers;

    /**
     * 身份证
     */
    @JSONField(name = "id_card")
    private String idCard;
}


Response-fields:

Field Type Description
subUserName string 用户名称
numbers number No comments found.
id_card string 身份证

Response-example:

{
	"subUserName":"黎昕.郑",
	"numbers":gzc1l6,
	"id_card":"370809198201092228"
}


2.4 请求参数忽略

开发中有时候我们可能有时候会直接使用数据库的对象模型去直接接收参数,但是像createTime、updateTime这样的字段我们是不希望输出到请求参数接口文档中。对于返回数据来说,其实比较好处理,smart-doc本身能够识别fastjson和jackson的字段忽略注解来过滤掉。对请求参数来说针对这种都没有好的解决,很多文档工具是通过添加注解,smart-doc经过使用频率和遵循不引入注解的原则,添加一个注释tag来提供请求参数过滤,这个注释tag定义为ignore。 注意:该功能在1.5版本才会有。

public class SubUser {

    /**
     * 用户名称
     */
    private String subUserName;

    /**
     * 身份证
     */
    private String idCard;

    /**
     * 性别
     * @required
     */
    private int gender;

    /**
     *  创建时间
     *  @ignore
     */
    private Timestamp createTime;

}


在Controller层用SubUser作为参数接收,smart-doc输出的参数请求文档:

Parameter Type Description Required
subUserName string 用户名称 false
numbers number No comments found. false
idCard string 身份证 false
gender int 性别 true

2.5 参数自动模拟值生成

smart-doc为了尽量减少开发人员和测试人员造参数值的时间,针对常见的字段类型和常用字段命名规则提供自动造参数值的功能。下面直接看用例:

public class SubUser {

    /**
     * 姓名
     */
    private String name;

    /**
     * 年龄
     */
    private int age;

    /**
     * 身份证
     */
    @JSONField(name = "id_card")
    private String idCard;

    /**
     * 性别(0,1)
     *
     */
    private int gender;

    /**
     * 电子邮件
     */
    private String email;

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

    /**
     *  创建时间
     *  @ignore
     */
    private Timestamp createTime;
}


下面是smart-doc自定生成文档中响应数据,这个数据全部依赖源码来推导完成。

Response-fields:

Field Type Description
name string 姓名
age int 年龄
id_card string 身份证
gender int 性别(0,1)
email string 电子邮件
phone string 手机号
createTime object 创建时间

Response-example:

{
	"name":"明轩.石",
	"age":59,
	"id_card":"350308197203301780",
	"gender":0,
	"email":"聪健.邱@gmail.com",
	"phone":"17664304058",
	"createTime":"2018-10-23 00:20:19"
}

2.6 添加文档变更记录

在1.7版本开始,smart-doc添加了文档变更记录的记录功能,生成的文档更加符合实际的文档交互场景。该功能需要在选择使用allInOne设置的时候才生效。 使用方式如下:

ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
config.setAllInOne(true);
config.setOutPath("d:\\md2");
//不指定SourcePaths默认加载代码为项目src/main/java下的
config.setSourceCodePaths(
    SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")
);
 //非必须项,只有当setAllInOne设置为true时文档变更记录才生效,
 //https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
config.setRevisionLogs(
 RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
 RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
);


变更记录在文档头部,markdown样式如下

版本 时间 状态 作者 备注
V1.0 2018/12/15 创建 chen 测试
V2.0 2018/12/16 修改 chen2 测试2

2.7 记录字段变更版本

smart-doc的用户在使用中提出了新增记录字段变更版本的需求。这样能够方便知道某一接口的接收参数字段或者是响应字段是什么时候新增的。秉承着简洁的原则,smart-doc在实现这一功能是并未引入额外的注释tag,而是直接利用了JAVA原生的@since这个tag来标记字段新增的版本。用例如下:

public class SubUser {

    /**
     * @since 1.0
     * 用户名称
     */
    private String subUserName;

    /**
     * 身份证
     */
    private String idCard;

    /**
     * 性别
     * @required
     */
    private int gender;

    /**
     *  创建时间
     *  @ignore
     */
    private Timestamp createTime;

}

Response-fields:

Field Type Description Required Since
subUserName string 用户名称 false 1.0
numbers number No comments found. false -
idCard string 身份证 false -
gender int 性别 true -

三、如何让smart-doc加载源码

Smart-doc作为一款完全依赖源码注释来分析生成文档的工具。如果没有源代码,那么在生成文档时将只能看到字段名和字段类型等信息,注释相关的信息都将无法生成,对于一个所有代码都在一个单独项目中的情况,你不需要考虑人和东西,Smart-doc能完美的完成你想要的文档,但是对一个多模块项目,或者项目依赖了一个独立的jar包的情况,smart-doc将无法加载到它所运行模块之外的代码。下面将会介绍如何来让Smart-doc加载到运行模块外的项目代码:

3.1 通过ApiConfig类设置

代码示例如下:

ApiConfig config = new ApiConfig();
//以前的版本为setSourcePaths,SourceCodePath为SourcePath
config.setSourceCodePaths(
        SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
        //smart-doc对路径自动会做处理,无论是window合适linux系统路径,直接拷贝贴入即可
        SourceCodePath.path().setDesc("加载外部项目源码").setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java")
);

这样smart-doc就能将外部的源码载入。

注意:smart-doc后续版本开发配套的插件可以实现自动加载source源码,推荐使用插件。

3.2 通过maven的classifier来指定源码包

这里先看如何使用classifier来加载源码包。

<!--依赖的库-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>[最新版本]</version>
</dependency>
<!--依赖库源码-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>[最新版本]</version>
    <classifier>sources</classifier>
    <!--设置为test,项目发布时source不会放入最终的产品包-->
    <scope>test</scope>
</dependency>

这样不需要像上面一样设置源码加载路径了。但是并不是所有的打包都能有源码包。需要在打包是做规范化处理。

注意:smart-doc后续版本开发配套的插件可以实现自动加载source源码,推荐使用插件。

公有jar包打规范

当你发布公共jar包或者dubbo应用api接口共有jar包时,在maven的plugs中加入maven-source-plugin,示例如下:

<!-- Source -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

这样发布的时候就会生成一个[your jar name]-sources.jar的源码包,这个包也会一起发布到私有仓库。这样就可以通过classifier来指定sources了。如果还是不清楚可以直接参考smart-doc源码的pom.xml配置。使用单元测试模式需要在依赖中配置,目前smart-doc的插件已经能够自动加载发布到仓库中sources.jar,推荐使用插件。

注意: 经测试如果只是通过install到本地,即便是指定了sources也无法读取到源码,只有将公用的模块deploynexus这样的私服上才能正常使用。

四、在Spring Boot项目中生成和展示html文档

smart-doc支持直接生成html静态文档,推荐生成的文档放到项目src/main/resources/static/doc的目录下,部署好服务后直接访问http://localhost:8080/doc/api.html即可看到一个类似gitbook带完美书签的html文档,文档风格简洁明了。操作步骤如下:

4.1 生成html文档

编写生成文档的单元测试;代码如下:

    /**
     * 包括设置请求头,缺失注释的字段批量在文档生成期使用定义好的注释
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //设置用md5加密html文件名,不设置为true,html的文件名将直接为controller的名称
        config.setMd5EncryptedHtmlName(true);
        config.setStrict(true);//true会严格要求注释,推荐设置true
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);//输出到static/doc下
        //不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
        config.setSourceCodePaths(
                SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")
        );
        long start = System.currentTimeMillis();
        HtmlApiDocBuilder.builderControllersApi(config);//此处使用HtmlApiDocBuilder,ApiDocBuilder提供markdown能力
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }

4.2 修改服务配置

如果Spring Boot服务配置了spring.resources.add-mappings=false,那么服务器将不会处理静态资源, smart-doc生成的html静态api文档也就不能访问,此时只需要将配置改为true即可。当然这种配置最好放入配置中心, 真正的生产服务器如果不希望暴露接口文档可以直接设置为false关闭文档。

4.3 html静态api展示效果

五、smart-doc自定义注释tag

tag名称 描述
@ignore ignore tag用于过滤请求参数对象上的某个字段,设置后smart-doc不输出改字段到请求参数列表中。
@required 如果你没有使用JSR303参数验证规范实现的方式来标准字段,就可以使用@required去标注请求参数对象的字段,标注smart-doc在输出参数列表时会设置为true。

最佳实践

首先smart-doc的实现思路是从源码出手,源码分析上存在着许多的难点,因此对接口代码的规范度要求很高。在smart-doc开源以来的反馈看,代码规范度高,碰到的问题也比较少。下面几点使用建议:

  • 建议公司内部代码尽量规范统一。

更多介绍

官方wiki

展开阅读全文
打赏
5
24 收藏
分享
加载中
大佬,我按说明配置了2.x版本的依赖,swagger ui 1.5,yml文件也配置了,"createDebugPage": true,属性无效,没有生成debug文件。使用的Pluhins. 编写测试类也无效
03/29 15:28
回复
举报
该评论暂时无法显示,详情咨询 QQ 群:912889742
在maven插件运行时报错:Execution default of goal com.github.shalousun:smart-doc-maven-plugin:2.0.5:html failed: Attempted to deserialize a java.lang.Class. Forgot to register a type adapter?。 请问该从哪里着手?
01/21 10:42
回复
举报
上官胡闹博主
应该是你的json配置有问题
01/21 11:50
回复
举报
该评论暂时无法显示,详情咨询 QQ 群:912889742
上官胡闹博主
请求头的常量目前好像不支持
01/22 12:51
回复
举报
另外,我想问下如果我想观察smartdoc是怎么进行代码扫描的应该从哪个类开始debug? 因为我手头有几个用了泛型的项目,扫描出来的值对象有一些问题(比如外部引用的jar中某个类的属性在表格中显示类型是string,但在Request-example里却是用{}展示成了对象),想自己观察一下。
01/21 13:23
回复
举报
您好。想问一下,我如何自定义返回BaseResult
01/18 19:38
回复
举报
你好,请我我在字段加了注解生成的文档依然是 No comments found.
2020/12/24 13:52
回复
举报
上官胡闹博主
smart-doc是基于源码的,没注释,通常是你的源码没被加载到,建议不要用单元测试,我们在文档中已经说明了,多看看wiki文档
2020/12/24 15:36
回复
举报
请问可以做到实时么,我更改了接口签名或类字段,会即时更新么
2020/03/23 17:15
回复
举报
上官胡闹博主
文档是你自己构建出来,我们有插件,改完代码运行下插件生成就可以了,团队规模成型,那么建议你通过jenkins等ci构建工具去构建代码,构建代码是就能生成文档。
2020/03/23 17:20
回复
举报
通过dependency导入源码后生成的文档中文乱码,直接以Junit运行测试没有中文乱码问题,但是解析不到第三方jar包中的注释,这个问题如何解决
2019/12/24 15:39
回复
举报
上官胡闹博主
这个可以结合我们项目上的wiki文档,检查环境,有些错误环境我们也不清楚,但是编码一般和smart-doc没有多大关系,smart-doc主要依赖于的你系统
2019/12/24 20:48
回复
举报
两个问题 :
1.对继承实体没有办法得到注解。
2.显示问题 Integer->int32 ; Long ->int64,是不是我哪里设置错了?
2019/10/31 08:54
回复
举报
上官胡闹博主
类型显示并不是只站在Java的角度考虑,显示没有问题,这是通用处理。注释没有显示一般是你的代码来自项目之外,可以仔细阅读本博客相关内容。
2019/10/31 09:37
回复
举报
ok 那泛型是不是还不行。
2019/11/06 16:04
回复
举报
上官胡闹博主
我们支持泛型,smart-doc现在使用的人真的不少,是经过很多验证的。如果有问题可以提issues
2019/11/06 16:08
回复
举报
swagger无外乎两个核心功能,一是提供api文档,二是能集成api测试。
我一直不愿意使用swagger就是因为侵入性太强了,宁愿手写markdown的api文档,然后用postman管理接口,也不允许代码中一坨一坨无关的注解。
smartdoc从注释入手,即规范强化了文档的编写又能提供源码文档之外的api功能,真的对得起smart的称谓。
2019/10/27 09:42
回复
举报
最强大的doc组件,强制要求了规范,也不会污染代码,欣喜之情溢于言表!
2019/10/24 16:36
回复
举报
上官胡闹博主
该评论暂时无法显示,详情咨询 QQ 群:912889742
更多评论
打赏
34 评论
24 收藏
5
分享
返回顶部
顶部