Skip to content
自由人的 BLOG

apiDoc 基础语法

文档, 软件开发
阅读量

apiDoc 可以通过文本生成体验良好的 API 文档页面,这些文本可以以注释的形式放在代码里,apiDoc 读取源码注释,就可以生成页面了,当然也可以与代码分开,写一些全是注释的文档,作为 apiDoc 生成文档页面的「源文件」。

整理一下 apiDoc 「源文件」内容写法的“最小必要知识”。其余内容,查文档。

基础

用一个「文档块」来描述一个 API,这个「文档块」也是实现 API 的代码的注释。

一个文档块以 /** 开始,*/ 结束。

一个例子:

这个例子描述了一个获取用户信息的 GET 方法。

  • @api {get} /user/:id Request User information 这一行内容是必需的,表示了这个 API 的 HTTP 方法(method),路径(path,这个例子中的路径带了一个参数),Request User information 是这个 API 的 title
  • @apiName 必须是唯一的,最好总是加上这个字段。
  • @apiGroup 最好也总是加上,用于把有关联的 API 放到一个组。
  • 其他字段比如 @apiError, @apiSuccess 等是可选的。

继承

可以通过「继承」复用「文档块」

上面的例子用 @apiDefine 定义了一个可复用的文档块 UserNotFoundError,然后在 GetUserPutUser 两个 API 文档块中通过 @apiUse UserNotFoundError 复用文档块。

注意,只能继承一层。


下面把 apiParams 专门挑出来。

apiParams

apiParams 用来描述 API 的参数,它并没有提供什么手段去区分是路由参数、URL 查询参数还是在 HTTP BODY 里的参数。

除了 field,其余内容都是可选的。如果写 @apiParam 时,给 field 加了一对中括号,这样是指定了这个 field 是个可选参数。

group 是给参数分组,type 指定参数的数据类型。

例子:

@apiParamExample 用来描述参数样例

typetitle 都是可选的。

例子:


一个完整的例子:

← 备案了← 上一篇