如何写接口文档？

最近项目进入二期，开始进行app接口的开发。跟着大神学习了如何写接口文档

Web API文档生成工具apidoc   http://www.jianshu.com/p/bb5a4f5e588a

官方地址                                         http://apidocjs.com/

/**
* 要闻
*
* @author  hhb  20160907
*
* @api {GET}  /news/news 要闻与国际
* @apiGroup   News
* @apiVersion 1.0.0
* @apiParam {string} p 平台
* @apiParam {string} v 版本号
* @apiParam {int} [offset=0] 查询起点
* @apiParam {int} [size=20] 每次获取数量
* @apiParam {int} [pid=4] 板块id，4：要闻  7：国际
* @apiSuccess {Object}  topNews  轮播图数据
* @apiSuccess {string}  img     轮播图片或头图
* @apiSuccess {string} post_title    标题
* @apiSuccess {string} post_modified 日期
* @apiSuccess {string} post_source  来源
* @apiSuccess {string} post_hits   阅读量
* @apiSuccessExample {json} 返回值
* {"status":1,"data":{"list":[{"id":"22874","post_title":"\u56fd\u535a\u91cd\u5f00\u8721\u50cf\u9986","post_source":"\u65b0\u534e\u7f51","post_modified":"2016-05-26 13:33:40","post_hits":"354","img":"20160614\/575fa8f799492.png"},{"id":"22867","post_title":"\u5317\u4eac\u6545\u5bab\u6682\u505c\u5c06\u6587\u7269\u51fa\u501f\u7ed9\u53f0\u5317\u6545\u5bab","post_source":"\u8054\u5408\u65e9\u62a5\u7f51","post_modified":"2016-05-25 16:10:46","post_hits":"108","img":"20160530\/574b882a468c6.jpg"},{"id":"22814","post_title":"\u6e56\u5357\u6c38\u5dde\u53d1\u73b0\u4e1c\u6c49\u65f6\u671f\u53e4\u5893\u7fa4  \u8ddd\u4eca1900\u4f59\u5e74\u5386\u53f2","post_source":"\u4e2d\u56fd\u65b0\u95fb\u7f51","post_modified":"2016-05-20 13:28:51","post_hits":"58","img":"20160520\/573ea1c49436c.jpg"},{"id":"22813","post_title":"\u201c\u5e26\u7740\u535a\u7269\u9986\u7684\u5c0a\u4e25\u8fdb\u5165\u5e02\u573a\u201d\u2014\u2014\u6545\u5bab\u516c\u5e03\u6587\u521b\u5f00\u53d1\u201c\u5341\u5927\u79d8\u7b08\u201d","post_source":"\u65b0\u534e\u793e","post_modified":"2016-05-20 09:18:44","post_hits":"55","img":"20160520\/573e6c05800cd.jpg"},{"id":"22812","post_title":"\u5168\u7403\u9996\u5ea7\u6708\u5b63\u535a\u7269\u9986\u5317\u4eac\u4eae\u76f8 \u9ad8\u79d1\u6280\u542b\u91cf\u7a81\u663e\u9177\u70ab\u6548\u679c","post_source":"\u4e2d\u56fd\u65b0\u95fb\u7f51","post_modified":"2016-05-20 08:46:26","post_hits":"25","img":"20160520\/573e5f990e953.jpg"},{"id":"22799","post_title":"\u201c2016\u5e74\u5168\u56fd\u6700\u5177\u521b\u65b0\u529b\u535a\u7269\u9986\u201d\u9881\u5956\u4eea\u5f0f\u5728\u5185\u8499\u53e4\u535a\u7269\u9662\u4e3e\u884c","post_source":"\u4e2d\u56fd\u6587\u7269\u4fe1\u606f\u7f51","post_modified":"2016-05-19 10:35:28","post_hits":"53","img":"20160519\/573d298910054.jpg"},{"id":"22775","post_title":"\u5317\u4eac90\u4f59\u9879\u6d3b\u52a8\u8fce\u63a5\u201c5\u00b718\u56fd\u9645\u535a\u7269\u9986\u65e5\u201d","post_source":"\u4e2d\u56fd\u6587\u7269\u4fe1\u606f\u7f51","post_modified":"2016-05-13 10:53:00","post_hits":"12","img":"20160517\/573ac74bc337f.jpg"}],"topNews":[{"id":"22900","post_title":"\u9996\u9875\u8f6e\u64ad\u56fe","post_source":" \u68b5\u8482\u5188\u53e4\u5178\u98ce\u683c\u68b5\u8482\u5188\u82ac","post_modified":"2016-06-12 13:09:36","post_hits":"25","img":"20160612\/575ceeab13226.jpg"},{"id":"22899","post_title":"vb\u4e2a\u4e0d\u9519\u5f04\u9519\u7f8e\u5973\u5417\u4e30\u5bcc","post_source":" \u5171\u548c\u56fd","post_modified":"2016-06-12 13:02:37","post_hits":"14","img":"20160612\/575ced054a3b1.jpg"},{"id":"22898","post_title":"\u6d4b\u8bd5\u4eca\u65e5\u8981\u95fb","post_source":"\u4e2d\u56fd\u6587\u7269\u62a5","post_modified":"2016-06-12 11:42:24","post_hits":"175","img":"20160612\/575cda8ec86fd.jpg"}]},"msg":""}
*/

生成的接口文档样式







至于如何使用、下载请自己研究，会让你受益很钱。