Home
Smart-doc从2018年8月在中国开源以来获得了很多年轻java web应用开发者的喜爱。在这里非常感谢那些敢于尝试用Smart-doc去帮助自己更快速完成工作的开发者。 这里也将它分享给其他的国家的java web应用开发者。
Smart-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题， 是为了帮助java web开发者能够仅仅通过在开发时写上规范的java标准注释就能快速生成一个简洁明了的接口文档， 同时也让开发者能够拥有一份简洁漂亮的代码，不被没有必要的代码所污染。
在当前许多的web项目中，我们都会直接使用JSR303来验证参数的合法性包括检验参数是否为必须参数等，smart-doc本身是为了帮助开发人员少去写一些无用的东西，整合标准的开发规范去帮助快速的生成文档。因此smart-doc自诞生那一刻起就已经支持JRS303验证规范。只要你写在字段上加了JSR303的验证注解或者是hibernate-validate的注解。smart-doc在输出请求参数文档时自动填写参数必填为true。请看代码片段：
public class User {
/**
* user name
*/
@NotEmpty
@Length(max = 5)
private String name;
/**
* alias
* @since 2.0
*/
private String alias;
/**
* birthday
*/
@NotBlank(message = "birthday can't be null")
@Pattern(regexp = "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", message = "Birth date format is incorrect.")
private String birthday;
/**
* age
*/
@Min(value = 0)
private Integer age;
}
Request-example:
| Parameter | Type | Description | Required | Since |
|---|---|---|---|---|
| name | string | user name | true | - |
| alias | string | alias | false | 2.0 |
| birthday | string | birthday | true | - |
| age | int | age | false | - |
smart-doc能够自动解析fastjson和jackson的忽略字段注解正确输出到文档中。这个比较简单就不详细介绍了。
smart-doc能够解析fastjson的JSONField注解的name属性值和spring boot原始的jackson的JsonProperty注解value属性值来自动完成别名输出。做过json字段忽略都知道，这里简单介绍。
public class User {
/**
* user name
*/
@NotEmpty
@Length(max = 5)
private String name;
/**
* alias
* @since 2.0
*/
private String alias;
/**
* birthday
*/
@NotBlank(message = "birthday can't be null")
@Pattern(regexp = "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", message = "Birth date format is incorrect.")
private String birthday;
/**
* age
*/
@Min(value = 0)
private Integer age;
}
Response-fields:
| Field | Type | Description | Required | Since |
|---|---|---|---|---|
| name | string | user name | true | - |
| alias | string | alias | false | 2.0 |
| birthday | string | birthday | true | - |
| age | int | age | false | - |
Response-example:
{
"name":"James",
"alias":"James Harden",
"birthday":"1999-09-30",
"age":"20"
}
开发中有时候我们可能有时候会直接使用数据库的对象模型去直接接收参数，但是像createTime、updateTime这样的字段我们是不希望输出到请求参数接口文档中。对于返回数据来说，其实比较好处理，smart-doc本身能够识别fastjson和jackson的字段忽略注解来过滤掉。对请求参数来说针对这种都没有好的解决，很多文档工具是通过添加注解，smart-doc经过使用频率和遵循不引入注解的原则，添加一个注释tag来提供请求参数过滤，这个注释tag定义为ignore。 注意：该功能在1.5版本才会有。
public class User {
/**
* user name
*/
private String userName;
/**
* gender
* @required
*/
private int gender;
/**
* create time
* @ignore
*/
private Timestamp createTime;
}
在Controller层用@RequestBody User user作为参数接收，smart-doc输出的请求参数文档：
| Parameter | Type | Description | Required | Since |
|---|---|---|---|---|
| userName | string | user name | false | - |
| gender | int | gender | true | - |
smart-doc为了尽量减少开发人员和测试人员造参数值的时间，针对常见的字段类型和常用字段命名规则提供自动造参数值的功能。下面直接看用例:
public class User {
/**
* user name
*/
private String name;
/**
* name
*/
private int age;
/**
* id card
*/
@JSONField(name = "id_card")
private String idCard;
/**
* gender
*
*/
private int gender;
/**
* email
*/
private String email;
/**
* telphone
*/
private String phone;
/**
* create time
* @ignore
*/
private Timestamp createTime;
}
下面是smart-doc自定生成文档中响应数据，这个数据全部依赖源码来推导完成。
Response-fields:
| Field | Type | Description | Since |
|---|---|---|---|
| name | string | user name | - |
| age | int | age | - |
| id_card | string | id_card | - |
| gender | int | gender | - |
| string | - | ||
| phone | string | phone | |
| createTime | String | create time | - |
Response-example:
{
"name":"James Harden",
"age":59,
"id_card":"350308197203301780",
"gender":0,
"email":"[email protected]",
"phone":"17664304058",
"createTime":"2018-10-23 00:20:19"
}
在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.setSourcePaths(
SourcePath.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 |
smart-doc支持直接生成html静态文档，推荐生成的文档放到项目src/main/resources/static/doc的目录下，部署好服务后直接访问http://localhost:8080/doc/api.html即可看到一个类似gitbook带完美书签的html文档，文档风格简洁明了。操作步骤如下：
编写生成文档的单元测试；代码如下：
/**
* 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
config.setStrict(true);//true会严格要求注释，推荐设置true
config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);//输出到static/doc下
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourcePaths(
SourcePath.path().setDesc("本项目代码").setPath("src/main/java")
);
//使用aes加密根据controller名称生成稳定的html文件名称，否则将直接显示controller名称
//因此推荐实际发布时使用aes加密文件名
config.setAesInfo(
//自行设置aes的key和iv，由于文件名并不是全加密串，整个项目使用时请保持统一
//因此即便泄露了也不能根据html文件名解密出controller的名称
ApiAesInfo.create().setKey(KEY).setVector(IV)
);
long start = System.currentTimeMillis();
HtmlApiDocBuilder.builderControllersApi(config);//此处使用HtmlApiDocBuilder，ApiDocBuilder提供markdown能力
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
如果Spring Boot服务配置了spring.resources.add-mappings=false，那么服务器将不会处理静态资源， smart-doc生成的html静态api文档也就不能访问，此时只需要将配置改为true即可。当然这种配置最好放入配置中心， 真正的生产服务器如果不希望暴露接口文档可以直接设置为false关闭文档。
首先smart-doc的实现思路是从源码出手，源码分析上存在着许多的难点，因此对接口代码的规范度要求很高。在smart-doc开源一年多以来的反馈看，代码规范度高，碰到的问题也比较少。下面几点使用建议：
- 尽量使用独立的参数接收对象，参数接收对象尽量避免使用枚举类(包含枚举属性)和使用内部类。
- 返回对象中也不要使用枚举类和内部类，可参考阿里开发规范手册。