apidoc 实践和自动化生成

更多腾讯海量技术文章,请关注云加社区:https://cloud.tencent.com/developer

作者:陈少文

导语

在前后端分离框架中,API 文档频繁交接。如果涉及到第三方接口调用,多方合作场景下,API 和文档变更可能会更快。为了方便维护 API 和交接文档,这里给大家推荐一款文档生成工具 - apidoc。

apidoc 简介

apidoc 是一个基于 nodejs 的 API 文档生成工具,从代码注释中提取特定格式的内容,生成 API 文档。

目前支持的语言有:C#、C/C 、D、Erlang、Go、Groovy、Java、Javascript、Pascal/Delphi、Perl、PHP、Python、Rust、Ruby、Scala 和 Swift。

特点:

跨平台,linux、windows、macOS 等都支持。

支持语言广泛。

支持文档版本管理。

支持多个不同语言的多个项目生成一份文档。

输出模板可自定义。

举个例子

以 Django 为例,在 views 函数中写注释

生成的 API 文档

apidoc 支持的关键字

apidoc 通过抽取代码注释,根据关键字语法生成 API 文档。所以,如果想生成理想的 API 文档,一定要遵循 apidoc 的相关关键字语法。下面是一个关键字语法的 list,{ }表示需要替换的变量,[ ]表示可选参数:

@api path [title]。

只有使用@api 标注的注释块才会在解析之后生成文档,title 会被解析为导航菜单(@apiGroup) 下的小菜单

method 可以有空格,如

@apiGroup name。

分组名称,被解析为导航栏菜单

@apiName name。

接口名称,在同一个@apiGroup 下,名称相同的@api 通过@apiVersion 区分,否者后面@api 会覆盖前面定义的@api

@apiDescription text。

接口描述,支持 html 语法

@apiVersion verison。

@apiIgnore [hint]。

apidoc 会忽略使用@apiIgnore 标注的接口,hint 为描述

@apiSampleRequest url。

接口测试地址以供测试,发送请求时,@api method 必须为 POST/GET 等其中一种

@apiDefine name [title] [description]。

定义一个注释块(不包含@api),配合@apiUse 使用可以引入注释块

在@apiDefine 内部不可以使用@apiUse

@apiUse name。

引入一个@apiDefine 的注释块

@apiParam [(group)] [] [field=defaultValue] [description]。请求参数

@apiHeader [(group)] [] [field=defaultValue] [description]。头部参数

@apiError [(group)] [] field [description]。响应错误时参数

@apiSuccess [(group)] [] field [description]。成功时参数,

group 表示参数的分组,type 表示类型(不能有空格),入参可以定义默认值(不能有空格)

@apiParamExample [] [title] example。参数请求用例

@apiHeaderExample [] [title] example。头部请求用例

@apiErrorExample [] [title] example。错误请求用例

@apiSuccessExample [] [title] example。成功请求用例

type 表示的是 example 的语言类型, example 内容会被直接解析显示。

@apiPermission name。

name 必须独一无二,描述@api 的访问权限,如 admin/anyone

安装配置 apidoc

安装 apidoc

这里默认已经安装了 nodejs,如果没有安装,请自行下载安装。全局安装 apidoc:

npm install apidoc -g

配置

配置是可选的,没有配置并不影响文档的生成。只是缺失部分 API 文档信息而已。在工程的根目录下,创建 apidoc.json 文件,配置文档的基本信息:

{ "name": "项目 API 文档", "version": "1.0.0", "description": "项目 API 文档-说明", "title": "项目 API 文档-title" }

生成文档

在 apidoc.json 所在的目录下,执行命令:

apidoc -i ./

-i 参数表示输入的目录,默认生成的文档在当前目录下的/doc,也可以通过-o 参数指定。

apidoc 自动生成

每次更新代码注释之后,执行一次apidoc -i ./才能看到 API 文档,比较麻烦。能不能每次修改注释之后,自动生成 API 文档呢?当然可以。

安装 gaze

gaze 是基于 nodejs 的文件监控项目。

npm install gaze -g

编写监控代码

执行监控

只需要更新注释之前,执行一次命令即可。

node apidoc-watch.js

项目实践建议

1 文档的交接方式

建议将 API 文档生成在前端的 static 目录下,以链接的形式交接,比如: htttp://example.com/static/doc/index.html。

2 后端注释组织方式

以 Django 为例,由于 apidoc 需要的注释量比较大,有两种选择:

一种是将注释直接写在每个 views 函数中,

一种是单独使用一个文件或文件夹来写注释。

django 中建议skinny controller, fat model,views.py 中少些代码,多写注释,第一种方案比较合适。同时,注释和接口实现放在一起,可以降低二次维护学习成本。

3 使用 apiDefine 和 apiUse

由于前后端,常常会约定固定格式的返回。可以将格式固定的部分,使用 apiDefine 定义为一个注释块,在其他地方使用 apiUse 引用。可以有效减少注释量。

定义注释块,注意:一个注释块应该被定义为一个单独的注释:

其他地方引用

def myview(request, id): """ @api ci/app/:id/ 获取应用详情 @apiVersion 1.0.0 @apiDescription 获取应用详情 @apiName getAppDetail @apiGroup Application @apiUse success """

4 合理使用 apiGroup 分组

apiGroup、apiName 会被拼接到 URL 中,比如:static/doc/index.html#api-apiGroup-apiName。给 apiGroup、apiName 取个容易理解的名字很重要。合理使用 apiGroup,将前端相关的功能聚集在一起,有利于前端理解 API 的用途。

参考

http://apidocjs.com/

https://github.com/shama/gaze

https://github.com/apidoc/apidoc

  • 发表于:
  • 原文链接:http://kuaibao.qq.com/s/20180115A0DHZC00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。

扫码关注云+社区

领取腾讯云代金券