使用apidoc文档神器，快速生成api文档

boredream 发布于2019-08-23 16:55 / 411人阅读

摘要：写完接口，就需要编写文档了，如果一个个手写的话就很麻烦，就得使用只需要通过写注释，就可以快速生成文档了。组将用于生成的输出中的主导航。输出文档到文件夹，没有回自动创建。执行访问就可以看到生成好的文档了。

写完api接口，就需要编写api文档了，如果一个个手写的话就很麻烦，就得使用apidoc只需要通过写注释，就可以快速生成文档了。

安装

第一步先安装全局模块apidoc。

npm install apidoc -g

修改接口的注释

找到novel-api项目routes下面的index.js文件，注释修改成如下

/**
 * @api {get} /index 请求首页数据
 * @apiVersion 1.0.0
 * @apiName 获取首页数据
 * @apiGroup index
 *
 *
 * @apiSuccess {Number} flag 是否获取到数据 1成功 0失败
 * @apiSuccess {Array} books 返回书籍内容
 * @apiSuccess {String} msg  返回信息
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *    {
 *      "flag": 1,
 *      "books": [
 *          {
 *             "_id": "5816b415b06d1d32157790b1",
 *            "title": "圣墟",
 *            "author": "辰东",
 *            "shortIntro": "在破败中崛起，在寂灭中复苏。沧海成尘，雷电枯竭，那一缕幽雾又一次临近大地，世间的枷锁被打开了，一个全新的世界就此揭开神秘的一角……",
 *            "cover": "http://statics.zhuishushenqi.com/agent/http%3A%2F%2Fimg.1391.com%2Fapi%2Fv1%2Fbookcenter%2Fcover%2F1%2F1228859%2F1228859_fac7917a960547eb953edf0b740cef3a.jpg%2F",
 *            "site": "zhuishuvip",
 *            "majorCate": "玄幻",
 *            "minorCate": "东方玄幻",
 *            "allowMonthly": false,
 *            "banned": 0,
 *            "latelyFollower": 283375,
 *            "retentionRatio": "73.42"
 *          }
 *      ],
 *      "msg": "OK"
 *    }
 *
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     { "flag": 0, "msg": "rankingId有问题" }
 */

@api {method} path [title]
@api 如果没有@api apidoc会忽略这段注释
method 请求的方法
path 路径
title 标题

@apiVersion version
设置文档块的版本。
version 版本号

@apiName name
定义方法文档块的名称。名称将用于生成的输出中的子导航。
name 方法的名称

@apiGroup name
定义方法文档块属于哪个组。组将用于生成的输出中的主导航。
name 组的名称。也用作导航标题。

@apiSuccess [(group)] [{type}] field [description]
成功返回参数。
(group) 可选所有参数将按这个名称分组。没有组，默认Success 200设置。
{type} 可选返回类型
field 返回标识符
description 描述

@apiParamExample [{type}] [title]

               example

参数请求示例。
{type} 可选响应格式
title 示例的简称
example 详细的例子

@apiErrorExample [{type}] [title]

             example

错误返回消息的示例，输出为预格式化代码。
{type} 可选响应格式
title 示例的简称
example 详细的例子

配置npm run doc

打开package.json文件增加doc命令配置

"doc": "apidoc -i routes/ -o public/"

routes/ 要输出API文档的文件夹。
public/ 输出文档到public文件夹，没有回自动创建。
执行 npm run doc
访问 http://localhost:3000/ 就可以看到生成好的API文档了。

线上生成的文档地址

https://api.langpz.com/

我的博客和github，喜欢就去点点星吧，谢谢。

https://github.com/lanpangzhi

http://blog.langpz.com

参考

https://github.com/apidoc/apidoc

混合云 idc机房托管生成API文档文档生成 python生成文档 python文档生成

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/103524.html

开源的api文档管理系统

摘要：国外的话国内的国内开源的非常好用的一款文档管理系统，安装也非常方便，只需将源代码放到项目目录下自动安装运行即可，不要要注意版本必须大于界面简洁功能强大的阿里的接口管理工具，开源免费，接口自动化，数据自动生成，自动化测试，企业级管理。在项目中，需要协同开发，所以会写许多API文档给其他同事，以前都是写一个简单的TXT文本或Word文档，口口相传，这种方式比较老土了，所以，需要有个api...

zsirfs 2019-06-27 14:58 评论0 收藏0
利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

roland_reed 2019-08-06 10:52 评论0 收藏0
利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

hiyayiji 2019-06-28 13:50 评论0 收藏0
利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

biaoxiaoduan 2019-08-21 16:41 评论0 收藏0
利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

shaonbean 2019-07-30 14:42 评论0 收藏0