使用ApiDoc

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

特性和使用

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

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

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

实践和绕过一些缺陷

输入参数区分url query body

"""
@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 自动生成文档
• 还没想好