smart-doc功能使用介绍

时间 2019-11-12

标签 smart doc 功能使用介绍繁體版

原文原文链接

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

1、简介

Smart-doc是一个彻底无侵入的java Rest Api文档生成工具。让用户的代码保持整洁一直是Smart-doc的核心理念。java

2、特殊功能介绍

2.1 JSR303支持

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

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;
}

参数请求文档：git

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的忽略字段注解正确输出到文档中。这个比较简单就不详细介绍了。github

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

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

public class SubUser {

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

    /**
     *
     */
    private BigInteger numbers;

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

Response-fields:spring

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版本才会有。apache

public class SubUser {

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

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

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

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

}

在Controller层用SubUser做为参数接收，smart-doc输出的参数请求文档：json

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	-

3、如何让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就能将外部的源码载入。

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

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

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

这样不须要像上面同样设置源码加载路径了。可是并非全部的打包都能有源码包。须要在打包是作规范化处理。

公有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配置。

注意： 经测试若是只是经过install到本地，即使是指定了sources也没法读取到源码，只有将公用的模块deploy到nexus这样的私服上才能正常使用。

4、在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展现效果

5、smart-doc自定义注释tag

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

最佳实践

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

尽可能使用独立的参数接收对象，参数接收对象尽可能避免使用枚举类(包含枚举属性)和使用内部类。
返回对象中也不要使用枚举类和内部类，可参考阿里开发规范手册。