文档章节

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

叶大侠
 叶大侠
发布于 2017/01/15 22:40
字数 1558
阅读 353
收藏 0

精选30+云产品,助力企业轻松上云!>>>

背景

之前有在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
  • 参数列表
参数名 类型 必需 描述
name String true 用户名
  • 返回结果:
{
  "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 开源项目
叶大侠

叶大侠

粉丝 63
博文 45
码字总数 69522
作品 5
广州
程序员
私信 提问
加载中
请先登录后再评论。
开源API文档工具- swagger2 与 smart-doc 比较 与 使用

工具开源地址 swagger2 : https://swagger.io/ smart-doc: https://www.oschina.net/p/smart-doc 国产 两者的比较 swagger2 和 smart-doc 两个开源工具 都可以 使用jar包 生成 api 文档。 ...

GavinWells
07/02
18
0
开源API文档工具- swagger2 与 smart-doc 比较 与 使用

工具开源地址 swagger2 : https://swagger.io/ smart-doc: https://www.oschina.net/p/smart-doc 国产 两者的比较 swagger2 和 smart-doc 两个开源工具 都可以 使用jar包 生成 api 文档。 ...

独行侠X
06/06
0
0
细说RESTful API之文档管理

目录 API文档格式 文档管理方式 基于注解实现,代码和文档在一起 基于API测试工具生成 独立编写文档 写在最后 规范的接口文档管理方式有助于提高组件协同(如:前后端分离)的开发效率,对于...

2Simple
2019/07/30
0
0
细说RESTful API之文档管理

目录 API文档格式 文档管理方式 基于注解实现,代码和文档在一起 Swagger Api2Doc 基于API测试工具生成 Postman rest-client 独立编写文档 RAP DOClever APIDOC CrapApi 写在最后 规范的接口...

osc_g6d2xdbw
2019/07/30
2
0
前后端分离,几个常用的API管理系统

为啥需要API管理系统! 互联网服务发展至今,作为开发者阵营的我们,已经用实践证明了前后端分离开发模式正在逐渐成为越来越多互联网公司构建服务和应用的方式。 前后端分离优势多多,其中一...

osc_dkusfncz
02/02
8
0

没有更多内容

加载失败,请刷新页面

加载更多

Node.js:无需尾随换行符即可打印到控制台? - Node.js: printing to console without a trailing newline?

问题: Is there a method for printing to the console without a trailing newline? 是否有一种无需尾随换行符即可打印到控制台的方法? The console object documentation doesn't say a......

javail
45分钟前
21
0
如何在屏幕底部对齐视图? - How to align views at the bottom of the screen?

问题: Here's my layout code; 这是我的布局代码; <?xml version="1.0" encoding="utf-8"?><LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orien......

fyin1314
今天
16
0
微信小程序如何修改小程序名称

如何修改微信小程序的名称。 微信小程序是在 app.json 中定义的。 你可用修改 app.json 中的 navigationBarTitleText": “云开发 QuickStart”, 字段。 xiug修改后保存,你就可以看到小程序的...

honeymoose
今天
27
0
将符合ISO 8601的字符串转换为java.util.Date - Converting ISO 8601-compliant String to java.util.Date

问题: I am trying to convert an ISO 8601 formatted String to a java.util.Date . 我正在尝试将ISO 8601格式的String转换为java.util.Date 。 I found the pattern yyyy-MM-dd'T'HH:mm:s......

富含淀粉
今天
17
0
jQuery选择器中的通配符 - Wildcards in jQuery selectors

问题: I'm trying to use a wildcard to get the id of all the elements whose id begin with "jander". 我正在尝试使用通配符来获取id以“jander”开头的所有元素的id。 I tried $('#jand......

法国红酒甜
今天
19
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部