使用ApiDoc

去年做meeting项目后台的时候,感觉需要api文档,于是找了下相关工具,就发现了ApiDoc。当时感觉勉强够用但是有很多缺陷,而且最好的Api文档生成方式应该是自动生成而非手写,所以只想临时用一下也没有安利的动力。不过随着越写越多,到今天(2016-11-19)已经有147个API使用了ApiDoc文档(好像换起来挺麻烦的)而且之前觉得是坑的地方也能通过实践来避免。于是就有了这个……来让大家一起避(lai)开(ru)坑

特性和使用

首先,任何介绍都不如官方的文档 APIDOC - Inline Documentation for RESTful

这是一个通过在Api方法中写注释,可以生成静态网页形式的API文档。有如下的优点

  • 首先,有文档总比没有好
  • 代码和文档离得很近,这样更新接口的时候不会忘记更新文档
  • 在各种接口继承的情况下,文档比代码更容易让后端找到接口的功能
  • 多个接口有相同输入/输出的情况下,可以用@ApiDefine来创建注释块到处引用

实践和绕过一些缺陷

输入参数区分url query body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
"""
@apiDefine InputService
@apiParam (Url) {Number} staff_id 工作人员ID
@apiParam (Query) {Number} [id] 服务ID
@apiParam (Query) {String} [model] 服务
@apiParam (Query) {Number} [brand_id] 品牌ID
@apiParam (Query) {Number} [shop_id] 门店ID
"""

class StaffCoursesShopsV2ApiView(StaffCoursesActionV2ApiView):
"""
@api {PUT} /api/v2/staffs/:staff_id/courses/:course_id/shops/ 健身房管理-课程种类适用场馆-修改
@ApiGroup Main

@apiUse InputService
@apiParam (Body) {Number} course_id 课程种类ID
@apiParam (Body) {String} shop_ids 适用场馆ID列表

@apiSuccess {Objects} course 课程版
@apiSuccess {String} course.something 卡具体信息(以下偷懒省略……)
"""
def some_function(self, *args, **kwargs):
pass

尤其在PUT/POST接口,参数可能在URL中,可能在URL后面的Query里面,还可能在请求体中。如果文档不加以区分会让前端很困惑。然后我发现了apiParam支持分组(所以并不是缺陷,只是我当时没发现这个feature)

只支持单级分类

在一个分类下,只能按照字符顺序来排。为了让文档美观些,我对API的命名是 二级模块名-操作资源名-操作 比如上一个例子

二级模块名可以换成操作人身份(如果不同身份的人访问同一资源使用不同的API)。理论上可以扩展出无限层,但是心智负担略大,并不推荐

如果发现自己的分类有毒,看起来就要改一堆的文档。所以要提前规划好

看起来很有用的特性

  • @apiError 可以列举出现错误时的返回

  • @apiSampleRequest @apiParamExample @apiSuccessExample @apiErrorExample 这些参数可以帮助前端更好的了解Api在输入实际参数的行为。

以上特性由于比较耗时&&小KD同学刚接触ApiDoc的时候没看到,所以没有使用过

未来

  • 提交代码后 git hock 自动生成文档
  • 还没想好

使用ApiDoc
https://blog.kdwycz.com/archives/use-apidoc/
作者
kdwycz
发布于
2016年12月1日
许可协议