关于java web restful api文档的重新探索

原创
2018/08/20 22:40
阅读数 1.5W
谁说生成api文档就必须要定义注解?
谁说生成接口请求和返回示例必须要在线?

用代码去探路,不断尝试更多文档交付的可能性。
如果代码有生命,为什么不换种方式和它对话!

一、背景

没有背景、就自己做自己的背景

在当今各种盛行的前后端分离、restful service开发过程中,接口文档是必不 可少的。对于前后端分离的开发中,后端开发需要将接口写好后需要告诉前端工程师接口的请求参数、响应示例等重要信息,而对于对外暴露的restful接口服务,我们提供接口也是需要具备相同的接口文档的。

但是对于后端工程师来讲,写接口文档将变成一个很大的工作量,虽然现在有类似apidoc、swagger这样的主流接口文档生成工具,但是如果实际用过,会发现这些工具不能满足实际需求,这里拿swagger为例,这个工具最大的优点能是提供在线的api文档,但是它天生就有很强的代码侵入性,要得到一个基本满足需求的api接口文档,必须在代码中使用swagger自定义的注解。这其实给开发人员增加学习成本和工作量,并且就算你使用大量的注解,有许多接口还是无法满足。因此不得不去做一次接口文档工具重新启航探索,smart-doc应允而生,用代码去探路,消除繁杂的注解,发现天下没有难写的接口文档。

二、smart-doc简介

简约而不简单

smart-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题,当然api-doc也是一款零注解完全基于源代码接口定义,使用java标准注释生成接口文档的工具。并且smart-doc代码也是完全开源的。目前生成的文档格式为markdown。

smart-doc的码云仓库链接

github仓库地址链接

三、功能特性

一个都不能少
  • 零注解、零学习成本、只需要写标准java注释。
  • 基于源代码接口定义自动推导。
  • 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
  • 支持Callable,Future,CompletableFuture等异步接口返回的推导。
  • 目前支持javabean上定义的部分fastjson和jackson注解。
  • 支持javabean上基于jsr303参数检验判断参数是否为必须。
  • 对json请求参数的接口能够自动生成模拟json参数。
  • 对一些常用字段定义能够生成有效的模拟值。
  • 支持生成json返回值示例。
  • 支持从项目外部加载源代码来生成字段注释。
  • 一款代码注释检测工具,明眼leader都知道接口文档直接反馈出注释情况。
  • 支持生成静态的html格式api,轻易实现在Spring Boot服务上在线查看api文档。

四、效率成效

效率是做好工作的灵魂。——切斯特菲尔德
  • 直接生成模拟请求参数,提升了团队里的前端和测试的工作效率,试想你让他们去编写json请求参数,如果你不写,鬼知道是什么样。
  • 后端开发只需专注业务和写好标准注释,无需引入额外注解,无需自己编写请求参数示例和响应示例。
  • 接口文档更加标准化

五、缺点

只有看到自己的不足,才能获得进步。
  • 由于基于源代码分析生成文档,因此无法生成在线文档,需要结合地方markdown文档管理工具来管理。
  • 由于源代码分析难度很大,针对很多代码存在潜在的大量的bug.
  • 对泛型返回接口需要明确定义泛型定义,否则无法推导

六、用例

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>[最新版本]</version>
</dependency>

6.1 定义bean

/**
 * @author yu 2018/8/4.
 */
public class SimpleUser {

    /**
     * 用户名
     */
    @NotNull
    private String username;

    /**
     * 密码
     */
    private String password;

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

    /**
     * 电话
     */
    private String mobile;

}

6.2 定义接口

/**
 * 用户信息操作接口
 * @author yu 2018/8/4.
 */

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

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

启动文档生成(官方不在推荐使用下面单元测试方式)

 /**
 * 包括设置请求头,缺失注释的字段批量在文档生成期使用定义好的注释
 */
@Test
public void testBuilderControllersApi() {
    ApiConfig config = new ApiConfig();
    config.setServerUrl("http://localhost:8080");
    config.setStrict(true);
    config.setOutPath("d:\\md");
    //不指定SourceCodePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
    config.setSourceCodePaths(
            SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")

           //  SourceCodePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"),
           // SourceCodePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
    );

    long start = System.currentTimeMillis();
    ApiDocBuilder.builderControllersApi(config);
    long end = System.currentTimeMillis();
    DateTimeUtil.printRunTime(end, start);
}

生成文档

添加用户

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

Type: post

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

Request-parameters:

Parameter Type Description Required
username string 用户名 true
password string 密码 false
nickName string 昵称 false
mobile string 电话 false

Request-example:

{
	"username":"瑞霖.张",
	"password":"xud2qc",
	"nickName":"rudy.goyette",
	"mobile":"15650966307"
}

Response-fields:

Field Type Description
username string 用户名
password string 密码
nickName string 昵称
mobile string 电话

Response-example:

[
	{
		"username":"浩然.阎",
		"password":"dzlv56",
		"nickName":"kieran.herzog",
		"mobile":"17863739656"
	}
]

demo地址:https://github.com/shalousun/api-doc-test

七、未来定义

期待下一次我们更好的相遇
  • 修改源代码解析的众多的bug
  • 收集使用者的建议,提供非json请求参数的请求示例
  • 收集使用者一些新增功能建议,增加一些必须功能。

八、使用协议

尊重别人,才能让人尊敬。——笛卡尔
  • 任何企业和个人不得用于申请专利

九、使用反馈

分享是一种生活的信念,明白了分享的同时,明白了存在的意义。

smart-doc的发展离不开你的支持,因为出于完全的开源免费,因此您可以基于smart-doc的源码解析核心上去做一些自定义的开发来将接口文档数据接入到一些第三方的在线api文档管理系统,例如:CrapApi,但是在请使用者能有一份开源的心态和情怀,积极反馈api-doc的核心代码使用bug和提出改善意见。<br/> 由于我个人的开发精力有限,对于是否会将smart-doc快速集成推送到第三方优秀的管理工具,短期内可能不会考虑,因此也希望使用者分享一些比较好的集成方案来供大家使用,如果方案比较符合smart-doc使用简洁的核心理念,将会直接纳入后续的版本升级中,同时源代码和方案提供者也将纳入smart-doc的开发者。

十、祝福

愿你编写接口无数,归来仍是少年

ps:转载请注明https://my.oschina.net/u/1760791/blog/write/1931071

展开阅读全文
打赏
8
25 收藏
分享
加载中
对象嵌套List对象生成解析不了
2019/10/17 20:49
回复
举报
上官胡闹博主
该评论暂时无法显示,详情咨询 QQ 群:912889742
上官胡闹博主

引用来自“帅的冒泡美的掉渣”的评论

一般都是返回ajaxresult这种,数据放data里,这种可以生成么?或是怎么申明data里放的类型?
controller层Result这样显示的申明接口返回类型就可以,可以参考提供的demo
2018/12/12 23:36
回复
举报
一般都是返回ajaxresult这种,数据放data里,这种可以生成么?或是怎么申明data里放的类型?
2018/12/12 21:44
回复
举报

引用来自“郁也风”的评论

好东西,不过完全零注解的话步子就有点大了,希望能在restdocs的基础上做增强,可能灵活性更强

引用来自“上官胡闹”的评论

其实零注解并不大,restdocs做法也不是这个工具的发展目标,这个偏向于大型企业的文档管理方式,最后是希望自动生成文档数据,一键发布到统一的文档管理中心
我准备参考你的部分代码(例如读取源码注释之类的)增强一下 restdocs,毕竟已经在不少地方用了这个了。
2018/08/30 20:09
回复
举报
上官胡闹博主

引用来自“郁也风”的评论

好东西,不过完全零注解的话步子就有点大了,希望能在restdocs的基础上做增强,可能灵活性更强
其实零注解并不大,restdocs做法也不是这个工具的发展目标,这个偏向于大型企业的文档管理方式,最后是希望自动生成文档数据,一键发布到统一的文档管理中心
2018/08/30 19:44
回复
举报
好东西,不过完全零注解的话步子就有点大了,希望能在restdocs的基础上做增强,可能灵活性更强
2018/08/30 16:09
回复
举报
看起来不错,对spring cloud项目支持的怎么样呀
2018/08/28 09:00
回复
举报
上官胡闹博主
该评论暂时无法显示,详情咨询 QQ 群:912889742
博主好,Demo中返回值是集合,但文档resp里面看不出是集合,这个就是这样的么?
2018/08/22 19:20
回复
举报
上官胡闹博主

引用来自“唐代de豆腐”的评论

需要的就是你 swagger恶心至死。😛
我是看不下去现在的绝大多数文档生成工具才开发的,使用过程中有问题可以给我反馈,这个是属于零注解,发布前也在码云上拉了些项目来做测试,
这种方式相对来说,只要接口显性的申明泛型,会直接得到很不错的文档
2018/08/22 17:40
回复
举报
更多评论
打赏
13 评论
25 收藏
8
分享
返回顶部
顶部