关于java web restful api文档的重新探索
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性。 如果代码有生命,为什么不换种方式和它对话!
一、背景
没有背景、就自己做自己的背景
在当今各种盛行的前后端分离、restful service开发过程中,接口文档是必不
可少的。对于前后端分离的开发中,后端开发需要将接口写好后需要告诉前端工程师接口的请求参数、响应示例等重要信息,而对于对外暴露的restful接口服务,我们提供接口也是需要具备相同的接口文档的。
但是对于后端工程师来讲,写接口文档将变成一个很大的工作量,虽然现在有类似apidoc、swagger这样的主流接口文档生成工具,但是如果实际用过,会发现这些工具不能满足实际需求,这里拿swagger为例,这个工具最大的优点能是提供在线的api文档,但是它天生就有很强的代码侵入性,要得到一个基本满足需求的api接口文档,必须在代码中使用swagger自定义的注解。这其实给开发人员增加学习成本和工作量,并且就算你使用大量的注解,有许多接口还是无法满足。因此不得不去做一次接口文档工具重新启航探索,api-doc应允而生,用代码去探路,消除繁杂的注解,发现天下没有难写接口文档。
二、api-doc简介
简约而不简单
api-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题,当然api-doc也是一款零注解完全基于源代码接口定义使用java标准注释生成接口文档的工具。并且api-doc代码也是完全开源的。目前生成的文档格式为markdown。
三、功能特性
一个都不能少
- 零注解、零学习成本、只需要写标准java注释。
- 基于源代码接口定义自动推导
- 支持springmvc、springboot
- 目前支持javabean上定义的部分fastjson和jackson注解
- 支持javabean上基于jsr303参数检验判断参数是否为必须
- 对json请求参数的接口能够自动生成模拟json参数
- 对一些常用字段定义能够生成有效的模拟值
- 支持生成json返回值示例
- 支持从项目外部加载源代码来生成字段注释
- 一款代码注解检测工具,明眼leader都知道接口文档直接反馈出注释情况
四、效率成效
效率是做好工作的灵魂。——切斯特菲尔德
- 直接生成模拟请求参数,提升了团队里的前端和测试的工作效率,试想你让他们去编写json请求参数,如果你不写,鬼知道是什么样。
- 后端开发只需专注业务和写好标准注释,无需引入额外注解,无需自己编写请求参数示例和响应示例。
- 接口文档更加标准化
五、缺点
只有看到自己的不足,才能获得进步。
- 由于基于源代码分析生成文档,因此无法生成在线文档,需要结合地方markdown文档管理工具来管理。
- 由于源代码分析难度很大,针对很多代码存在潜在的大量的bug.
- 对泛型返回接口需要明确定义泛型定义,否则无法推导
六、用例
<dependency> <groupId>com.github.shalousun</groupId> <artifactId>api-doc</artifactId> <version>0.5</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"); //不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载 config.setSourcePaths( SourcePath.path().setDesc("本项目代码").setPath("src/main/java") // SourcePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"), // SourcePath.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请求参数的请求示例
- 收集使用者一些新增功能建议,增加一些必须功能。
八、使用协议
尊重别人,才能让人尊敬。——笛卡尔
- 任何企业和个人不得用于申请专利
九、使用反馈
分享是一种生活的信念,明白了分享的同时,明白了存在的意义。
Api-doc的发展离不开你的支持,因为出于完全的开源免费,因此您可以基于api-doc的源码解析核心上去做一些自定义的开发来将接口文档数据接入到一些第三方的在线api文档管理系统,例如:CrapApi,但是在请使用者能有一份开源的心态和情怀,积极反馈api-doc的核心代码使用bug和提出改善意见。
由于我个人的开发精力有限,对于是否会将api-doc快速集成推送到第三方优秀的管理工具,短期内可能不会考虑,因此也希望使用者分享一些比较好的集成方案来供大家使用,如果方案比较符合api-doc使用简洁的核心理念,将会直接纳入后续的版本升级中,同时源代码和方案提供者也将纳入api-doc的开发者。
十、祝福
愿你编写接口无数,归来仍是少年
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
Python全栈 MongoDB 数据库(数据的查找)
非关系型数据库和关系型数据库的区别? 不是以关系模型构建的,结构自由 非关系型数据库不保证数据一致性 非关系型数据库可以在处理高并发和海量数据时弥补关系数据库的不足 非关系型数据库在技术上没有关系型数据库技术成熟 查找操作: db.集合名.find(查找条件,域) 查找条件: 键值对的形式给出要展示的文档 域: 以键值对对的形式给出要展示或不展示的域 0为值不显示该域 1为值显示该域 如果使用0设置某些域不显示默认其他域显示 如果使用1设置某些域显示默认其他域不显示 *_id 只有设置为0才不显示否则默认显示 除_id以外,其他域必须同时设置0或1 db.集合名.findOne(查找条件,域) 查找复合条件的第一条文档 查找条件(query): 操作符: 使用$注明的一特殊意义的字符串,表达某个特定含义 比如:$gt表示大于 语法: db.集合名.find({name:{$gt:"tom"}}, {_id:0}) 比较操作符: $eq 等于 $lt 小于(字符串也可以比较大小) $lte 小于等于 $gt 大于 $gte 大于等于 $ne 不等于 $...
- 下一篇
CentOS7 下配置 Nginx + PHP7 + MariaDB + ThinkPHP5.1
最近突然想学习一下使用一些比较成熟的后台框架,考虑到之前帮大佬打下手的时候用过 ThinkPHP 所以就暂定了以 ThinkPHP 为主要学习目标。 下面是我在服务器端配置 Thinkphp 所需环境而踩的一些坑(且有很多已经是老坑了): 本次配置选择的服务器系统为 Centos7 环境是 Nginx + PHP7 + MariaDB + ThinkPHP5.1 我会按照我个人认为合适的顺序分别介绍他们的安装与配置过程 1. MariaDB 的安装与初始配置 # yum 安装 yum -y install mariadb mariadb-server # 安装完成MariaDB,首先启动MariaDB systemctl start mariadb # 设置开机启动 systemctl enable mariadb # 接下来进行MariaDB的相关简单配置 mysql_secure_installation #首先是设置密码,会提示先输入密码 Enter current password for root (enter for none):# 初次运行直接回车 #设置密码 Set r...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- SpringBoot2整合Redis,开启缓存,提高访问速度
- CentOS7安装Docker,走上虚拟化容器引擎之路
- SpringBoot2配置默认Tomcat设置,开启更多高级功能
- CentOS7编译安装Cmake3.16.3,解决mysql等软件编译问题
- Docker安装Oracle12C,快速搭建Oracle学习环境
- CentOS8安装Docker,最新的服务器搭配容器使用
- CentOS7设置SWAP分区,小内存服务器的救世主
- SpringBoot2全家桶,快速入门学习开发网站教程
- Docker使用Oracle官方镜像安装(12C,18C,19C)
- CentOS6,7,8上安装Nginx,支持https2.0的开启