增加apidoc模块生成api文档，不过接口描述我只写了一个

.gitignore

@@ -20,6 +20,7 @@ desktop.ini
 
 .idea
 public/upload/*
+public/apidoc/*
 
 *.sublime-project
 *.sublime-workspace

api/v1/topic.js

@@ -11,6 +11,49 @@ var at           = require('../../common/at');
 var renderHelper = require('../../common/render_helper');
 var validator    = require('validator');
 
+
+/**
+ * @api {get} /v1/topics 主题列表
+ * @apiDescription
+ * 获取本站主题列表
+ * @apiName getTopics
+ * @apiGroup topic
+ *
+ * @apiParam {Number} page 页数
+ * @apiParam {String} tab 主题分类。目前有 ask share job good
+ * @apiParam {Number} limit 每一页的主题数量
+ * @apiParam {String} mdrender 当为 false 时，不渲染。默认为 true，渲染出现的所有 markdown 格式文本
+ *
+ * @apiPermission none
+ * @apiSampleRequest /v1/topics
+ *
+ * @apiVersion 1.0.0
+ *
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {
+          "success": true,
+          "data": [
+              {
+                  "id": "",
+                  "author_id": "",
+                  "tab": "ask",
+                  "content": "",
+                  "title": "",
+                  "last_reply_at": "",
+                  "good": false,
+                  "top": false,
+                  "reply_count": 2,
+                  "visit_count": 8,
+                  "create_at": "",
+                  "author": {
+                      "loginname": "admin",
+                      "avatar_url": "//gravatar.com/avatar/80579ac37c768d5dffa97b46bb4754f2?size=48"
+                  }
+              }
+          ]
+      }
+ */
 var index = function (req, res, next) {
   var page     = parseInt(req.query.page, 10) || 1;
   page         = page > 0 ? page : 1;

apidoc.json

@@ -0,0 +1,10 @@
+{
+  "name": "API说明",
+  "version": "1.0.0",
+  "description": "API接口文档",
+  "apidoc": {
+    "title": "API接口文档",
+    "url" : "/api"
+  },
+  "sampleUrl": "http://localhost:3000/api"
+}

config.default.js

@@ -23,6 +23,7 @@ var config = {
   // 右上角的导航区
   site_navs: [
     // 格式 [ path, title, [target=''] ]
+    [ '/public/apidoc/', 'API' ],
     [ '/about', '关于' ]
   ],
   // cdn host，如 http://cnodejs.qiniudn.com

controllers/static.js

@@ -32,6 +32,3 @@ exports.robots = function (req, res, next) {
   }));
 };
 
-exports.api = function (req, res, next) {
-  res.render('static/api');
-};

package.json

@@ -53,6 +53,7 @@
     "xss": "0.2.10"
   },
   "devDependencies": {
+    "apidoc": "^0.17.5",
     "errorhandler": "1.4.3",
     "istanbul": "0.4.2",
     "loader-connect": "1.0.1",
@@ -64,6 +65,7 @@
     "supertest": "1.2.0"
   },
   "scripts": {
-    "test": "make test"
+    "test": "make test",
+    "apidoc": "./node_modules/.bin/apidoc -i api/ -o public/apidoc"
   }
 }

views/layout.html

@@ -91,7 +91,6 @@
         </li>
         <% } %>
         <li><a href='/getstart'>新手入门</a></li>
-        <li><a href='/api'>API</a></li>
         <%
         var site_navs = config.site_navs || [];
         for (var i = 0, l = site_navs.length; i < l; i++) {

web_router.js

@@ -104,7 +104,6 @@ router.get('/about', staticController.about);
 router.get('/faq', staticController.faq);
 router.get('/getstart', staticController.getstart);
 router.get('/robots.txt', staticController.robots);
-router.get('/api', staticController.api);
 
 //rss
 router.get('/rss', rss.index);