ApiDoc + github page 运用

2019年8月20日 170次阅读 来源: Mike晓

你的项目在用什么东西誊写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
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞