文档章节

API文档生成工具设计与实现

叶大侠
 叶大侠
发布于 2017/01/15 22:40
字数 1558
阅读 110
收藏 0
点赞 0
评论 0

背景

之前有在IDE端根据API文档生成相关接口的数据模型,这减少了客户端这边的工作量,具体可以看上一篇文章:Model代码插件开发。后面想到如果直接让服务端订好接口的代码规范,那么就可以通过写个工具把API文档,Android和IOS的数据模型代码一并生成了,这样既减少了客户端的工作量,又能减少服务端人员的工作量(不用再去手工维护接口文档)。

我们先来看看最终的效果:点击查看

设计思路

服务端环境

目前服务端的API接口是通过Play1.4版本框架来写的,通过研究服务端的代码结构,不难知道它的路由是通过一个conf/routes配置文件来维护的,它的结构如下:

# api
POST    /api/admin/auth    api.admin.AdminController.auth
GET     /api/game/list     api.game.GameController.list
GET     /api/messageList   api.MyController.messageList

#是注释,一条路由从左到右分别是[请求方法,请求接口,具体调用所在类的方法],结构非常清晰。

我们来看一下具体某个接口代码:

/**
 * @Description 消息列表接口
 * @param type 消息类型0是系统消息;1是回复我的;2是点赞我的;
 * @param page 页码 从1开始
 * @author yedaxia
 */
@ApiResult(name = MessageListResult.class)
public void messageList(@Required int type, @Required int page) {
	renderJSON();
}

方法的参数和请求的参数一致,注解是一些验证,如果有,表示该参数是必须要传的。

API描述信息

api是客户端和服务端通信的接口,一般是http或者https作为协议载体,主要包含了请求信息和返回的信息。

请求信息:

  • 基本信息
接口作用描述
接口作者: yedaxia
method:POST
url: api.github/updateUserinfo
  • 参数列表
参数名类型必需描述
nameStringtrue用户名
  • 返回结果:
{
  "id": "long //用户id",
  "name": "String //用户昵称",
  "gender": "int //用户性别(1:男;2:女;0:未知)",
  "avatar": "String //用户头像",
  "token": "String //用户token",
  "isNewUser": "int //是否是新用户"
}

返回结果我们用json数据结构表示,这样在多层的数据结构中可读性更强,而且许多应用也是采用的json格式作为返回结果,我们在相应的字段后加入类型和相关的注释。有了这些信息之后,对于客户端开发人员来说就很清晰了,有问题也可以根据作者找到相关的后端人员。

建立关联关系

  1. 基本信息 可以读取routes的路由信息; 接口描述读取方法上的@Description注释信息,接口作者 读取相关接口方法的@author注释。

  2. 参数列表中的参数可以读取方法中参数,参数名类型很容易就对应上,如果有注解@Required或者其他的就视为必传参数,相关注释读取@param注释,这些都和java的编程习惯保持一致。

  3. 返回结果这个就不好直接知道了,通过协商,决定通过添加一个注解来完成,这可能也是唯一增加了服务端工作的一个地方,前面看到的@ApiResult(name = MessageListResult.class)就是我们定义返回结果了,MessageListResult是个简单的JavaBean对象,里面的每个字段和返回的字段一一对应。生成的结果应该支持数组或者列表,类的组合,继承等;每个字段都有类型和相关的注释信息。

展示形式

一开始是打算通过生成markdown的代码,后面发现从markdown转成html代码的几个java库生成效果不是特别理想,最后还是决定通过html模板来实现。

每个Controller作为一个API集合,放在一个单独的文件中,通过锚点和目录的方式来实现方便的跳转。

实现结果

最终的实现效果可以点击这里进行查看,至此,我们API文档的完整性和规范性完全交给代码本身进行维护,并自动生成了相关客户端的数据模型代码,有效减少了大家的工作量,实施效果非常好。

相关代码和例子已经上传到github了,由于当前只能支持Play框架,如果大家有兴趣可以提相关issue或者自己去研读代码,提交自己的实现,笔者有时间会考虑支持其他框架。

进一步思考

我一直倡导项目组的开发应该接口设计先行,定下接口协议后各端就可以并行开发了。但是据我了解,还是有不少团队是服务端人员先把接口的逻辑代码写的差不多再交付给客户端接口文档的。通过这个文档生成工具,服务端人员更加愿意提前先设计好接口了,靠工具生成漂亮的文档提前交付未实现的接口给下游人员,而又没有多少增加工作量,整个开发过程会变得更加愉快。虽然整个流程看起来已经比较顺畅了,但是在应付接口变化还需要进一步的努力,除了接口设计上的扩展性应该更好一些之外,在文档工具上后续会考虑加入ChangeLog。

参考资料

  1. Java反射获取方法的参数名列表
  2. apidoc 开源项目

© 著作权归作者所有

共有 人打赏支持
叶大侠

叶大侠

粉丝 56
博文 44
码字总数 67312
作品 5
广州
程序员
RESTful API 设计参考文献--restful-api-design-references

restful-api-design-references是RESTful API 设计参考文献列表,可帮助你更加彻底的了解REST风格的接口设计。 RESTful 介绍及设计思路 Principles of good RESTful API Design(译:好 REST...

匿名 ⋅ 2016/09/12 ⋅ 2

使用swagger 生成 Flask RESTful API

什么是 RESTful 什么是REST REST(英文:Representational State Transfer,又称具象状态传输)是Roy Thomas Fielding博士于2000年在他的博士论文 中提出来的一种万维网软件架构风格,目的是...

goodspeed ⋅ 2017/07/11 ⋅ 0

liushoukun/restfulapi-tp5

Dawn-Api [Toc] 说明 thinkphp5编写的restful风格的API,集API请求处理,权限认证,自动生成文档等功能; restful风格处理请求 每个接口对于一个控制器,method对应[method]方法响应 权限认证...

liushoukun ⋅ 2017/02/21 ⋅ 0

一起聊聊:Kubernetes状态管理与扩展

本文通过一个具体实例介绍 Kubernetes 扩展开发,分析了 API Server 的兼容性设计;基于部分源码介绍了 Kubernetes API 聚合层原理和实现;最后还分析了 Kubernetes 提供的工具链和客户端抽象...

FreeWheel ⋅ 05/04 ⋅ 0

KBEngine v1.1.8 发布,分布式游戏服务端引擎

分布式游戏服务端引擎 KBEngine v1.1.8 发布了。更新如下: 新增与改善: 更新API文档。 BUG修正: 修正SDK生成工具,在linux生成的目录不正确(#595) 修正SDK生成工具生成UnitySDK时浮点数错...

开源中国部长_柯标 ⋅ 05/28 ⋅ 0

php开发工具

1 设计工具 2 编码工具 3 测试工具 4 部署工具 5 管理工具 设计工具 UML和相关设计工具 Argo UML UML绘图工具,支持PHP stub生成。-–Java编写。 Umbrello UML UML绘图工具,支持PHP stub生成...

“寒流” ⋅ 2011/04/26 ⋅ 2

ASMSupport 0.4 版本发布,Java 字节码操作

ASMSupport 0.4发布,0.4版本主要改变是采用了全新的Dummy方式的API来生成class,比如希望生成如下代码 public class FirstCase { public static void main(String[] args) { System.out.pri...

Erroooooor ⋅ 2015/04/07 ⋅ 6

小程序 102800 以及新版 WEPT 的改动

上一版微信小程序 0.10.102800 带来了许多的变化,以至于我一度以为 WEPT 这个主打热更新的小工具没什么继续存在的必要了,然而尽管我看到了小程序团队对于完善开发工具的不懈努力,它的体验...

赵启明 ⋅ 2016/11/15 ⋅ 0

iOS 移动端生成工具开发

上个月的一篇移动端面向文档开发一文久违的被编辑推荐到了首页, 也引来了饿了么大神的关注, 虽然最后实力不济未被录用, 但也指明了我前进的方向. 从4月到现在从一个想法到一步步的实现, 感觉...

Castie1 ⋅ 2017/08/21 ⋅ 0

iOS 移动端生成工具开发

上个月的一篇移动端面向文档开发一文久违的被编辑推荐到了首页, 也引来了饿了么大神的关注, 虽然最后实力不济未被录用, 但也指明了我前进的方向. 从4月到现在从一个想法到一步步的实现, 感觉...

Castie1 ⋅ 2017/11/25 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Springboot2 之 Spring Data Redis 实现消息队列——发布/订阅模式

一般来说,消息队列有两种场景,一种是发布者订阅者模式,一种是生产者消费者模式,这里利用redis消息“发布/订阅”来简单实现订阅者模式。 实现之前先过过 redis 发布订阅的一些基础概念和操...

Simonton ⋅ 28分钟前 ⋅ 0

error:Could not find gradle

一.更新Android Studio后打开Project,报如下错误: Error: Could not find com.android.tools.build:gradle:2.2.1. Searched in the following locations: file:/D:/software/android/andro......

Yao--靠自己 ⋅ 昨天 ⋅ 0

Spring boot 项目打包及引入本地jar包

Spring Boot 项目打包以及引入本地Jar包 [TOC] 上篇文章提到 Maven 项目添加本地jar包的三种方式 ,本篇文章记录下在实际项目中的应用。 spring boot 打包方式 我们知道,传统应用可以将程序...

Os_yxguang ⋅ 昨天 ⋅ 0

常见数据结构(二)-树(二叉树,红黑树,B树)

本文介绍数据结构中几种常见的树:二分查找树,2-3树,红黑树,B树 写在前面 本文所有图片均截图自coursera上普林斯顿的课程《Algorithms, Part I》中的Slides 相关命题的证明可参考《算法(第...

浮躁的码农 ⋅ 昨天 ⋅ 0

android -------- 混淆打包报错 (warning - InnerClass ...)

最近做Android混淆打包遇到一些问题,Android Sdutio 3.1 版本打包的 错误如下: Android studio warning - InnerClass annotations are missing corresponding EnclosingMember annotation......

切切歆语 ⋅ 昨天 ⋅ 0

eclipse酷炫大法之设置主题、皮肤

eclipse酷炫大法 目前两款不错的eclipse 1.系统设置 Window->Preferences->General->Appearance 2.Eclipse Marketplace下载【推荐】 Help->Eclipse Marketplace->搜索‘theme’进行安装 比如......

anlve ⋅ 昨天 ⋅ 0

vim编辑模式、vim命令模式、vim实践

vim编辑模式 编辑模式用来输入或修改文本内容,编辑模式除了Esc外其他键几乎都是输入 如何进入编辑模式 一般模式输入以下按键,均可进入编辑模式,左下角提示 insert(中文为插入) 字样 i ...

蛋黄Yolks ⋅ 昨天 ⋅ 0

大数据入门基础:SSH介绍

什么是ssh 简单说,SSH是一种网络协议,用于计算机之间的加密登录。 如果一个用户从本地计算机,使用SSH协议登录另一台远程计算机,我们就可以认为,这种登录是安全的,即使被中途截获,密码...

董黎明 ⋅ 昨天 ⋅ 0

web3j教程

web3j是一个轻量级、高度模块化、响应式、类型安全的Java和Android类库提供丰富API,用于处理以太坊智能合约及与以太坊网络上的客户端(节点)进行集成。 汇智网最新发布的web3j教程,详细讲解...

汇智网教程 ⋅ 昨天 ⋅ 0

谷歌:安全问题机制并不如你想象中安全

腾讯科技讯 5月25日,如今的你或许已经对许多网站所使用的“安全问题机制”习以为常了,但你真的认为包括“你第一个宠物的名字是什么?”这些问题能够保障你的帐户安全吗? 根据谷歌(微博)安...

问题终结者 ⋅ 昨天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部