ApiDoc + github page 运用

2019-08-20 00:00:00 github ApiDoc page

你的项目在用什么东西誊写api文档?本日就来给人人引荐下ApiDoc

1. ApiDoc是什么?

ApiDoc能够依据你再代码里的解释,来天生api形貌文档,如许就不用你本身去通知端的小伙伴该怎样挪用你的api了。如今支撑的变成言语有:Java,Javascript,Php,Python,C#,Ruby,Lua等,主流的编成言语都支撑。

2. 怎样用?

很简单,只需在你的代码里用如许的注解说明你的接口信息就好

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *  * @apiParam {Number} id Users unique ID.
 *  * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

这里面的这些注解都是ApiDoc定义好的,你只需根据官方文档运用就好了。ApiDoc 官网

3. 最先搞起来

  • 装置
npm install apidoc -g
  • 运转
apidoc -i api/ -o docs/

api是你的代码目次也就是你运用解释的文件目次,它会自动扫描运用注解的文件。docs文件时你要天生api文档的目次,也是github page末了要运用的目次。

  • 搜检api文档

在docs目次下直接翻开index.html就能够检察终究效果了。
《ApiDoc + github page 运用》

4. github page

github page 是一项免费的web效劳,它许可你把你的静态页面宣布出去共其他用户经由过程浏览器检察。适才我们天生的文档内容都在我们当地,如今我们须要把它宣布到github上

  • 建立github堆栈
  • 将本身的天生后的戴阿曼上船,就是docs全部目次
  • 在堆栈的 setting中开启page效劳
  • 用page供应的url去接见

总结

ApiDoc供应了更好的api文档浏览体验,关于开发者来讲免去了写文档的贫苦。不过不足就是不能像swagger那样供应在线调试,而且要想形貌一个api须要些许多的解释。

    原文作者:Mike晓
    原文地址: https://segmentfault.com/a/1190000017145798
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。

相关文章