Api 接口文档是什么？如何直接使用 ApiDoc 生成接口文档
api接口文档
现代化开发大部分都是一种前后端分离的开发模式，前端与后端分别独立进行开发。等后续再去统一的联调。前后端分离的开发模式下，前后端沟通的成本增加，如何减少口头的交流成了关键。这时有一份高端大气的接口文档就非常开心了。
是什么
一份描述了后端每个API接口的详细文档。主要需要如下几点信息：
- 请求方式
- 请求地址
- 请求参数
- 后端响应
这就引入一个新的问题，联调是什么，会出现什么问题？
联调
前端去在代码中去调用后台提供的api接口，并验证是否ok没问题。
联调会出现很多的问题：
- 后台返回的数据用不上或者缺少数据
- api接口调用不通，比如500 404
- api接口跨域问题
（跨域产生的原因：域名、协议、端口有一个不同就会产生跨域。是浏览器的同源策略引起的）
针对跨域问题，该如何解决？可以参考以下文章:
如何写
- 手写 word 、markdown、记事本都是可以的。
- 通过一些工具来生成，省时省力。
使用步骤
- 安装 apidoc（建议在当前项目下面安装）
$ npm install apidoc
apidoc 提供了一个 apidoc 的命令，可以通过 apidoc -v 去验证。
由于这块我们是本地安装，要验证 apidoc 命令的话有如下三种方式：
- cd node_modules/.bin 再去 apidoc -v- npx apidoc -v (npx 是 npm 5.x 版本之后提供的一个命令)- package.json 中写脚本
- 在每一个路由代码前写上 apidoc 规定的注释信息
/*** @api {put} http://localhost:3000/posts/:id 更新帖子* @apiName update* @apiGroup posts(帖子操作)** @apiParam {String} title 帖子标题* @apiParam {String} content 帖子内容* * @apiSuccess {Number} code 错误状态码.* @apiSuccess {String} msg 错误信息.*/
- 在项目根目录下创建一个 apidoc.json 文件，配置 api 接口文档的一些描述信息
{"name": "帖子管理系统的接口文档","version": "0.1.0","description": "我自己写哒"}
- 通过 apidoc 的命令去生成 api 接口文档
$ apidoc -i 写注释的路径 -o 文档输出路径$ apidoc -i ./routers -o ./public/docs
可以在package.json文件中将第四步代码做如下设置：
"docs":"apidoc -i ./routers -o ./public/docs"
每次更新routers文件里面的API接口文档内容时，只需要运行一下
npm run docs
就可以了
Api 接口文档是什么？如何直接使用 ApiDoc 生成接口文档
api接口文档
现代化开发大部分都是一种前后端分离的开发模式，前端与后端分别独立进行开发。等后续再去统一的联调。前后端分离的开发模式下，前后端沟通的成本增加，如何减少口头的交流成了关键。这时有一份高端大气的接口文档就非常开心了。
是什么
一份描述了后端每个API接口的详细文档。主要需要如下几点信息：
- 请求方式
- 请求地址
- 请求参数
- 后端响应
这就引入一个新的问题，联调是什么，会出现什么问题？
联调
前端去在代码中去调用后台提供的api接口，并验证是否ok没问题。
联调会出现很多的问题：
- 后台返回的数据用不上或者缺少数据
- api接口调用不通，比如500 404
- api接口跨域问题
（跨域产生的原因：域名、协议、端口有一个不同就会产生跨域。是浏览器的同源策略引起的）
针对跨域问题，该如何解决？可以参考以下文章:
如何写
- 手写 word 、markdown、记事本都是可以的。
- 通过一些工具来生成，省时省力。
使用步骤
- 安装 apidoc（建议在当前项目下面安装）
$ npm install apidoc
apidoc 提供了一个 apidoc 的命令，可以通过 apidoc -v 去验证。
由于这块我们是本地安装，要验证 apidoc 命令的话有如下三种方式：
- cd node_modules/.bin 再去 apidoc -v- npx apidoc -v (npx 是 npm 5.x 版本之后提供的一个命令)- package.json 中写脚本
- 在每一个路由代码前写上 apidoc 规定的注释信息
/*** @api {put} http://localhost:3000/posts/:id 更新帖子* @apiName update* @apiGroup posts(帖子操作)** @apiParam {String} title 帖子标题* @apiParam {String} content 帖子内容* * @apiSuccess {Number} code 错误状态码.* @apiSuccess {String} msg 错误信息.*/
- 在项目根目录下创建一个 apidoc.json 文件，配置 api 接口文档的一些描述信息
{"name": "帖子管理系统的接口文档","version": "0.1.0","description": "我自己写哒"}
- 通过 apidoc 的命令去生成 api 接口文档
$ apidoc -i 写注释的路径 -o 文档输出路径$ apidoc -i ./routers -o ./public/docs
可以在package.json文件中将第四步代码做如下设置：
"docs":"apidoc -i ./routers -o ./public/docs"
每次更新routers文件里面的API接口文档内容时，只需要运行一下
npm run docs
就可以了