apidoc [8.6k]生成文档
最后更新于：2022-04-02 03:10:06
[TOC]
> [http://apidocjs.com/](http://apidocjs.com/)
## 概述
1. 夸语言生成脚本
2. 带接口的版本管理
3. 可在接口文档中执行(url 或表单提交)
4. 可继承(如继承错误返回实例)
## 安装
`npm install apidoc -g `
`apidoc -i myapp/ -o apidoc/ -t mytemplate/
`
## 教程
配置apidoc.json
```
{
"name": "apidoc-example",
"version": "0.4.0",
"description": "apidoc example project",
"title": "Custom apiDoc browser title",
"url" : "https://localhost:8080",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"template": {
"withCompare": true, //是否进行版本对比
"withGenerator": false, //是否输出页脚信息
"forceLanguage":"zh_cn",
}
}
```
## 继承(公用基础模版)
### demo公用错误信息
`_apidoc.js`
```
/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
```
调用
```
/*
* @apiUse UserNotFoundError
*/
```
## 版本设置
_apidoc.js
```
/**
* @api {get} /user/:id Get User information
* @apiVersion 0.1.0
* /
```
```
/**
* @api {get} /user/:id Get User information and Date of Registration.
* @apiVersion 0.2.0
* /
```
## 可识别 html 标签
```
@apiError UserNotFound The
';
id of the user
was not found. ``` ## 推荐模版 [https://github.com/EvandroViva/apidocjs\_template](https://github.com/EvandroViva/apidocjs_template) ## 接口说明 ### @apiDeprecated 弃用说明 ``` /** * @apiDeprecated use now (#Group:Name). * * Example: to set a link to the GetDetails method of your group User * write (#User:GetDetails) */ ``` > 如果需要在显示接口文档时,中文表示,`locales\zh_cn.js`,添加 `"DEPRECATED":"弃用" ### @apiError `@apiError [(group)] [{type}] field [description] ` #### demo 直接使用 ` @apiError UserNotFound3 ` #### 定义apiDefine _apidoc.js ``` /** * @apiDefine UserNotFound * @apiError (Error) {String} UserNotFound Theid of the User was not found.
*/
/**
* @apiDefine UrlNotFound2
* @apiError (Error) {String} UserNotFound2 The id of the User was not found.
*/
```
```
/*
*@apiUse UserNotFound2
*/
```
### @apiParam 请求参数
```
//默认
@apiParam {Number} id this is a test
//带默认值
@apiParam {Number} id=123 this is a test
//可选参数
@apiParam {Number} \[id=123\] this is a test
//取值范围
@apiParam {Number{100~900}} id this is a test
@apiParam {String{2..5}} id this is a test
//允许值
@apiParam {number=1,2,3} id this is a test
@apiParam {string="small","huge"} id this is a test
```
### @apiSuccess
返回参数
```
//常规
@apiSuccess {String} firstname Firstname of the User.
//设置组
@apiSuccess (code 200) {string} name this is name
//设置第二层返回字段
@apiSuccess {Object} profile User profile information.
@apiSuccess {Number} profile.age Users age.
```
### @apiSuccessExample 成功示例
```
@apiSuccessExample {json} 成功返回
{
"firstname": "John",
"lastname": "Doe"
}
```
### @apiExample 可用curl 做测试
```
@apiExample {curl} Example usage:
curl -i http://localhost/user/4711
```
### @apiPermission
权限设置
直接填写
```
@apiPermission admin
```
添加说明
_apidoc.js
```
/**
* @apiDefine admin 权限说明
* 只有admin用户才可调用
*/
```
调用
```
@apiPermission admin
```
### @apiErrorExample
```
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
```
#### demo
`git clone https://github.com/apidoc/apidoc`
```
apidoc -i example -o doc -t template/
```
### @apiHeader
header 信息
`@apiHeader {String} access-key Users unique access-key.
`
### @apiIgnore 忽略某个接口
```
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
```
### @apiPrivate
设置接口为私有值
```
/**
* @api {get} /user/:id
* @apiPrivate
*/
```
普通编译 忽略 `@apiPrivate`
通过 `apidoc ---private true` 取消忽略
### @apiSampleRequest
可直接在文档发送测试请求
> [详情](http://apidocjs.com/#param-api-sample-request)