apiDoc 一款很不错api文档生成工具

apiDoc 一款很不错api文档生成工具，在开发接口的时候，需要给同事看相应的接口文档。给大家推荐一个生成文档的工具--apiDoc，最后生成的文档以网页的形式发布，方便快捷，便于阅读。

创建项目目录

不多说。。。

1、安装模块

apidoc 依赖node.js的包管理工具npm进行安装，所以安装apidoc之前要先安装node.js（npm会在安装node时顺带进行安装）。

node 的安装教程可以参考→Node软件的安装流程

$ npm install apidoc -g  # 或者
$ yarn add apidoc --global

2、配置package.json

"apidoc": {
  "title": "千锋HTML5学院",
  "url" : "http://localhost:3000/"
}

3、简单使用示例

apidoc是运用各个不同的注解来完成文档的写作的。学习apidoc，主要就是学习注解的用法。

详情可看官网 https://apidocjs.com/

常用的关键字

@apiVersion verison
  接口版本，major.minor.patch的形式
@api {method} path [title]
  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
  method如{POST GET}
@apiGroup name
  分组名称，被解析为导航栏菜单
@apiName name
  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescription text
  接口描述，支持html语法
  
@apiIgnore [hint]
  apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequest url
  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种

@apiDefine name [title] [description]
  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
  在@apiDefine内部不可以使用@apiUse
@apiUse name
  引入一个@apiDefine的注释块

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本类似，分别描述请求参数、头部，响应错误和成功
  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法完全一致，但是type表示的是example的语言类型
  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)
  
@apiPermission name
  name必须独一无二，描述@api的访问权限，如admin/anyone

index.js

const express = require('express');
const cors = require('cors');
const app = express(); // 无需设置 utf-8的编码格式，默认就是

app.use(cors());
app.use(express.urlencoded({ extended: false }));
app.use(express.json());

// 设置静态目录
app.use('/apidoc', express.static('apidoc'));

let users = [
  { id: 5, name: '刘仪', gender: '男', old: 22 },
  { id: 2, name: '张霞', gender: '女', old: 19 },
  { id: 1, name: '赵翔', gender: '男', old: 21 }
];

app.get('/', (req, res) => {
  console.log('home');
  res.send('<h1>首页</h1><p>建设中...</p>'); // 默认就是解析输出
});

/**
 * @api {get} /users 1 获取用户列表
 * @apiGroup users
 */
app.get('/users', (req, res) => {
  res.send(users);
});

/**
 * @api {post} /users 2 新增用户
 * @apiGroup users
 *
 * @apiParam  {String} name='张三' 姓名
 * @apiParam  {String} gender='男' 性别
 * @apiParam  {Number} old=19 年龄
 */
app.post('/users', (req, res) => {
  const len = users.length;
  let newId = len + 1;
  let ids = [];

  // 1 把id取出来
  users.forEach((user) => {
    ids.push(user.id);
  });
  // 2 升序排序
  ids.sort();
  // 3 判断是否有空缺
  for (let id = 1; id <= len; id++) {
    console.log(id);
    if (id !== ids[id - 1]) {
      newId = id;
      break;
    }
  }

  users.push({
    id: newId,
    name: req.body.name,
    gender: req.body.gender,
    old: req.body.old
  });

  res.send(users);
});

/**
 * @api {put} /users/:id 3 修改用户
 * @apiGroup users
 *
 * @apiParam  {String} name='张三' 姓名
 * @apiParam  {String} gender='男' 性别
 * @apiParam  {Number} old=19 年龄
 */
app.put('/users/:id', (req, res) => {
  const index = users.findIndex((user) => user.id == req.params.id);

  if (index != -1) {
    users.splice(index, 1, {
      id: req.params.id,
      name: req.body.name,
      gender: req.body.gender,
      old: req.body.old
    });
  }

  res.send(users);
});

/**
 * @api {delete} /users/:id 4 删除用户
 * @apiGroup users
 */
app.delete('/users/:id', (req, res) => {
  const index = users.findIndex((user) => user.id == req.params.id);

  if (index != -1) {
    users.splice(index, 1);
  }

  res.send(users);
});

app.listen(3000, () => {
  console.log('your server is running at http://localhost:3000');
});

apiDoc 一款很不错api文档生成工具 

4、编写完成后运行，生成在线接口文档

# -i 编译文件目录  -e 排除目录(不编译)  -o 文档输出目录
$ apidoc -i ./ -e node_modules -o apidoc

5、访问接口文档

http://localhost:3000/apidoc

apiDoc 一款很不错api文档生成工具，更多免费资料领取