Skip to content

Commit

Permalink
doc: add api doc
Browse files Browse the repository at this point in the history
  • Loading branch information
lizheming committed Sep 20, 2021
1 parent c3a438e commit 39de903
Show file tree
Hide file tree
Showing 5 changed files with 204 additions and 3 deletions.
7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@
"client:build": "npm run build:normal --workspace=@waline/client && npm run build:no-style --workspace=@waline/client && npm run build:dts --workspace=@waline/client",
"client:dev": "npm run dev --workspace=@waline/client",
"server:dev": "vercel dev ./example --listen 9090",
"docs:build": "npm run build --workspace=docs",
"docs:build": "npm run build --workspace=docs && npm run apidoc",
"docs:dev": "npm run dev --workspace=docs",
"apidoc": "apidoc -i packages/server/src/logic -o docs/.vuepress/dist/api",
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
"lint": "eslint --fix . && prettier --check --write .",
"lint:check": "eslint . && prettier --check .",
Expand Down Expand Up @@ -64,6 +65,7 @@
"@vue/eslint-config-prettier": "6.0.0",
"@vue/eslint-config-typescript": "7.0.0",
"babel-jest": "^27.2.0",
"apidoc": "^0.29.0",
"babel-loader": "^8.2.2",
"commitizen": "^4.2.4",
"conventional-changelog-cli": "^2.1.1",
Expand Down Expand Up @@ -104,5 +106,8 @@
"webpack-cli": "^4.8.0",
"webpack-dev-server": "^4.2.1",
"webpack-merge": "^5.8.0"
},
"apidoc": {
"title": "Waline API Documentation"
}
}
118 changes: 118 additions & 0 deletions packages/server/src/logic/comment.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,96 @@ module.exports = class extends Base {
}
}

/**
* @api {GET} /comment Get comment list for client
* @apiGroup Comment
* @apiVersion 0.0.1
*
* @apiParam {String} path comment url path
* @apiParam {String} page page
* @apiParam {String} pagesize page size
*
* @apiSuccess (200) {Number} page return current comments list page
* @apiSuccess (200) {Number} pageSize to return error message if error
* @apiSuccess (200) {Object[]} data comments list
* @apiSuccess (200) {String} data.nick comment user nick name
* @apiSuccess (200) {String} data.mail comment user mail md5
* @apiSuccess (200) {String} data.link comment user link
* @apiSuccess (200) {String} data.objectId comment id
* @apiSuccess (200) {String} data.browser comment user browser
* @apiSuccess (200) {String} data.os comment user os
* @apiSuccess (200) {String} data.insertedAt comment created time
* @apiSuccess (200) {String} data.avatar comment user avatar
* @apiSuccess (200) {String} data.type comment login user type
* @apiSuccess (200) {Object[]} data.children children comments list
* @apiSuccess (200) {String} data.children.nick comment user nick name
* @apiSuccess (200) {String} data.children.mail comment user mail md5
* @apiSuccess (200) {String} data.children.link comment user link
* @apiSuccess (200) {String} data.children.objectId comment id
* @apiSuccess (200) {String} data.children.browser comment user browser
* @apiSuccess (200) {String} data.children.os comment user os
* @apiSuccess (200) {String} data.children.insertedAt comment created time
* @apiSuccess (200) {String} data.children.avatar comment user avatar
* @apiSuccess (200) {String} data.children.type comment login user type
*/
/**
* @api {GET} /comment?type=list Get comment list for admin
* @apiGroup Comment
* @apiVersion 0.0.1
*
* @apiParam {String} page page
* @apiParam {String} pagesize page size
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
* @apiSuccess (200) {Object} data
* @apiSuccess (200) {Number} data.page comments list current page
* @apiSuccess (200) {Number} data.pageSize comments list page size
* @apiSuccess (200) {Number} data.totalPages comments list total pages
* @apiSuccess (200) {Number} data.spamCount spam comments count
* @apiSuccess (200) {Number} data.waitingCount waiting comments count
* @apiSuccess (200) {Object[]} data.data comments list data
* @apiSuccess (200) {String} data.data.ip comment user ip address
* @apiSuccess (200) {String} data.data.nick comment user nick name
* @apiSuccess (200) {String} data.data.mail comment user mail md5
* @apiSuccess (200) {String} data.data.link comment user link
* @apiSuccess (200) {String} data.data.objectId comment id
* @apiSuccess (200) {String} data.data.status comment status, approved, waiting or spam
* @apiSuccess (200) {String} data.data.ua comment user agent
* @apiSuccess (200) {String} data.data.insertedAt comment created time
* @apiSuccess (200) {String} data.data.avatar comment user avatar
* @apiSuccess (200) {String} data.data.url comment article link
*/
/**
* @api {GET} /comment?type=count Get comment count for articles
* @apiGroup Comment
* @apiVersion 0.0.1
*
* @apiParam {String} url a array string join by comma just like `a` or `a,b`
*
* @apiSuccessExample {Number} Single Path Response:
* 300
* @apiSuccessExample {Number} Multiple Path Response:
* [300, 100]
*/
/**
* @api {GET} /comment?type=recent Get recent comments
* @apiGroup Comment
* @apiVersion 0.0.1
*
* @apiParam {String} count return comments number, default value is 10
*
* @apiSuccess (200) {Object[]} response
* @apiSuccess (200) {String} response.nick comment user nick name
* @apiSuccess (200) {String} response.mail comment user mail md5
* @apiSuccess (200) {String} response.link comment user link
* @apiSuccess (200) {String} response.objectId comment id
* @apiSuccess (200) {String} response.browser comment user browser
* @apiSuccess (200) {String} response.os comment user os
* @apiSuccess (200) {String} response.insertedAt comment created time
* @apiSuccess (200) {String} response.avatar comment user avatar
* @apiSuccess (200) {String} response.type comment login user type
*/
getAction() {
const { type } = this.get();
switch (type) {
Expand Down Expand Up @@ -79,6 +169,34 @@ module.exports = class extends Base {
}
}

/**
* @api {POST} /comment post comment
* @apiGroup Comment
* @apiVersion 0.0.1
*
* @apiParam {String} nick post comment user nick name
* @apiParam {String} mail post comment user mail address
* @apiParam {String} link post comment user link
* @apiParam {String} comment post comment text
* @apiParam {String} url the artcile url path of comment
* @apiParam {String} ua browser user agent
* @apiParam {String} pid parent comment id
* @apiParam {String} rid root comment id
* @apiParam {String} at parent comment user nick name
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
* @apiSuccess (200) {Object} data return comment data
* @apiSuccess (200) {String} data.nick comment user nick name
* @apiSuccess (200) {String} data.mail comment user mail md5
* @apiSuccess (200) {String} data.link comment user link
* @apiSuccess (200) {String} data.objectId comment id
* @apiSuccess (200) {String} data.browser comment user browser
* @apiSuccess (200) {String} data.os comment user os
* @apiSuccess (200) {String} data.insertedAt comment created time
* @apiSuccess (200) {String} data.avatar comment user avatar
* @apiSuccess (200) {String} data.type comment login user type
*/
postAction() {
const { LOGIN } = process.env;
const { userInfo } = this.ctx.state;
Expand Down
9 changes: 8 additions & 1 deletion packages/server/src/logic/oauth.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
const Base = require('./base');

module.exports = class extends Base {};
module.exports = class extends Base {
/**
* @api {GET} /oauth/github github oauth api
* @apiGroup OAuth
* @apiVersion 0.0.1
*/
githubAction() {}
};
45 changes: 44 additions & 1 deletion packages/server/src/logic/token.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,46 @@
const Base = require('./base');

module.exports = class extends Base {};
module.exports = class extends Base {
/**
* @api {GET} /token get login user info
* @apiGroup User
* @apiVersion 0.0.1
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
* @apiSuccess (200) {Object} data user info
* @apiSuccess (200) {String} data.avatar user avatar
* @apiSuccess (200) {String} data.createdAt user register time
* @apiSuccess (200) {String} data.display_name user nick name
* @apiSuccess (200) {String} data.emal user email address
* @apiSuccess (200) {String} data.github user github account name
* @apiSuccess (200) {String} data.mailMd5 user mail md5
* @apiSuccess (200) {String} data.objectId user id
* @apiSuccess (200) {String} data.type user type, administrator or guest
* @apiSuccess (200) {String} data.url user link
*/
getAction() {}

/**
* @api {POST} /token user login
* @apiGroup User
* @apiVersion 0.0.1
*
* @apiParam {String} email login user email
* @apiParam {String} password login user password
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
*/
postAction() {}

/**
* @api {DELETE} /token user logout
* @apiGroup User
* @apiVersion 0.0.1
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
*/
deleteAction() {}
};
28 changes: 28 additions & 0 deletions packages/server/src/logic/user.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,34 @@
const Base = require('./base');

module.exports = class extends Base {
/**
* @api {POST} /user user register
* @apiGroup User
* @apiVersion 0.0.1
*
* @apiParam {String} display_name user nick name
* @apiParam {String} email user email
* @apiParam {String} password user password
* @apiParam {String} url user link
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
*/
postAction() {}

/**
* @api {PUT} /user update user profile
* @apiGroup User
* @apiVersion 0.0.1
*
* @apiParam {String} display_name user new nick name
* @apiParam {String} url user new link
* @apiParam {String} password user new password
* @apiParam {String} github user github account name
*
* @apiSuccess (200) {Number} errno 0
* @apiSuccess (200) {String} errmsg return error message if error
*/
putAction() {
const { userInfo } = this.ctx.state;
if (think.isEmpty(userInfo)) {
Expand Down

0 comments on commit 39de903

Please sign in to comment.