我们推荐使用 apidoc 作为 api 文档的自动生成工具，虽然很多人会使用 swagger，个人认为 swagger 的代码入侵性比较强，我们希望基于 cloudopt-next 项目是尽量少的代码、尽量简单的项目。所以我们再经过很长一段时间的调研后觉得推荐 apidoc

文档: apidocjs.com

示例 output.

安装

  1. $ npm install -g apidoc

使用

在路由方法上添加类似的注释:

  1. /**
  2.  * @api {get} /user/:id Request User information
  3.  * @apiName GetUser
  4.  * @apiGroup User
  5.  *
  6.  * @apiParam {Number} id User's unique ID.
  7.  *
  8.  * @apiSuccess {String} firstname Firstname of the User.
  9.  * @apiSuccess {String} lastname  Lastname of the User.
  10.  */

我们现在扫描 src/ 文件夹下的所有文件并将结果输出到 doc/.

  1. $ apidoc -i src/ -o doc/

如果你是 Kotlin ，并且希望在同一个网站访问的话你可以用下面的方法：

  1. apidoc -f ".*\\.kt$" -i src/main/kotlin/ -o src/main/resources/static/apidoc

接下来你可以通过 http://localhost:8080/static/apidoc 访问了。