OpenServer/OpenAuth_server
1
1
Fork 0
Code Issues Pull Requests Actions Releases Wiki Activity

Adding Basic API Documentation

Browse Source
This commit is contained in:
Fabian Stamm
2019-03-14 18:10:39 -04:00
parent e09c6df9f6
commit 18ea5de8aa
21 changed files with 828 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
src/api/admin/client.ts
View File

@ -1,29 +1,60 @@
import { Router, Request } from "express";
import { GetUserMiddleware } from "../middlewares/user";
import RequestError, { HttpStatusCode } from "../../helper/request_error";
import promiseMiddleware from "../../helper/promiseMiddleware";
import Client from "../../models/client";
import User from "../../models/user";
import verify, { Types } from "../middlewares/verify";
import { randomBytes } from "crypto";
const ClientRouter: Router = Router();
ClientRouter.use(GetUserMiddleware(true, true), (req: Request, res, next) => {
if (!req.isAdmin) res.sendStatus(HttpStatusCode.FORBIDDEN)
else next()
});
ClientRouter.route("/")
/**
* @api {get} /admin/client
* @apiName AdminGetClients
*
* @apiGroup admin_client
* @apiPermission admin
*
* @apiSuccess {Object[]} clients
* @apiSuccess {String} clients._id The internally used id
* @apiSuccess {String} clients.maintainer
* @apiSuccess {Boolean} clients.internal
* @apiSuccess {String} clients.name
* @apiSuccess {String} clients.redirect_url
* @apiSuccess {String} clients.website
* @apiSuccess {String} clients.logo
* @apiSuccess {String} clients.client_id Client ID used outside of DB
* @apiSuccess {String} clients.client_secret
*/
.get(promiseMiddleware(async (req, res) => {
let clients = await Client.find({});
//ToDo check if user is required!
res.json(clients);
}))
.delete(promiseMiddleware(async (req, res) => {
let { id } = req.query;
await Client.delete(id);
res.json({ success: true });
}))
/**
* @api {get} /admin/client
* @apiName AdminAddClients
*
* @apiGroup admin_client
* @apiPermission admin
*
* @apiParam {Boolean} internal Is it an internal app
* @apiParam {String} name
* @apiParam {String} redirect_url
* @apiParam {String} website
* @apiParam {String} logo
*
* @apiSuccess {Object[]} clients
* @apiSuccess {String} clients._id The internally used id
* @apiSuccess {String} clients.maintainer
* @apiSuccess {Boolean} clients.internal
* @apiSuccess {String} clients.name
* @apiSuccess {String} clients.redirect_url
* @apiSuccess {String} clients.website
* @apiSuccess {String} clients.logo
* @apiSuccess {String} clients.client_id Client ID used outside of DB
* @apiSuccess {String} clients.client_secret
*/
.post(verify({
internal: {
type: Types.BOOLEAN,
@ -49,11 +80,48 @@ ClientRouter.route("/")
await Client.save(client)
res.json(client);
}))
ClientRouter.route("/:id")
/**
* @api {delete} /admin/client/:id
* @apiParam {String} id Client _id
* @apiName AdminDeleteClient
*
* @apiGroup admin_client
* @apiPermission admin
*
* @apiSuccess {Boolean} success
*/
.delete(promiseMiddleware(async (req, res) => {
let { id } = req.params;
await Client.delete(id);
res.json({ success: true });
}))
/**
* @api {put} /admin/client/:id
* @apiParam {String} id Client _id
* @apiName AdminUpdateClient
*
* @apiGroup admin_client
* @apiPermission admin
*
* @apiParam {Boolean} internal Is it an internal app
* @apiParam {String} name
* @apiParam {String} redirect_url
* @apiParam {String} website
* @apiParam {String} logo
*
* @apiSuccess {String} _id The internally used id
* @apiSuccess {String} maintainer UserID of client maintainer
* @apiSuccess {Boolean} internal Defines if it is a internal client
* @apiSuccess {String} name The name of the Client
* @apiSuccess {String} redirect_url Redirect URL after login
* @apiSuccess {String} website Website of Client
* @apiSuccess {String} logo The Logo of the Client (optional)
* @apiSuccess {String} client_id Client ID used outside of DB
* @apiSuccess {String} client_secret The client secret, that can be used to obtain token
*/
.put(verify({
id: {
type: Types.STRING,
query: true
},
internal: {
type: Types.BOOLEAN,
optional: true
@ -85,4 +153,5 @@ ClientRouter.route("/")
res.json(client);
}))
export default ClientRouter;

8
src/api/admin/index.ts
View File

@ -3,8 +3,16 @@ import ClientRoute from "./client";
import UserRoute from "./user";
import RegCodeRoute from "./regcode";
import PermissionRoute from "./permission";
import { GetUserMiddleware } from "../middlewares/user";
import RequestError, { HttpStatusCode } from "../../helper/request_error";
const AdminRoute: Router = Router();
AdminRoute.use(GetUserMiddleware(true, true), (req: Request, res, next) => {
if (!req.isAdmin) throw new RequestError("You have no permission to access this API", HttpStatusCode.FORBIDDEN);
else next()
});
AdminRoute.use("/client", ClientRoute);
AdminRoute.use("/regcode", RegCodeRoute)
AdminRoute.use("/user", UserRoute)

52
src/api/admin/permission.ts
View File

@ -8,13 +8,22 @@ import Client from "../../models/client";
import { ObjectID } from "bson";
const PermissionRoute: Router = Router();
PermissionRoute.use(GetUserMiddleware(true, true), (req: Request, res, next) => {
if (!req.isAdmin) res.sendStatus(HttpStatusCode.FORBIDDEN)
else next()
});
PermissionRoute.route("/")
/**
* @api {get} /admin/permission
* @apiName AdminGetPermissions
*
* @apiParam client Optionally filter by client _id
*
* @apiGroup admin_permission
* @apiPermission admin
*
* @apiSuccess {Object[]} permissions
* @apiSuccess {String} permissions._id The ID
* @apiSuccess {String} permissions.name Permission name
* @apiSuccess {String} permissions.description A description, that makes it clear to the user, what this Permission allows to do
* @apiSuccess {String} permissions.client The ID of the owning client
*/
.get(promiseMiddleware(async (req, res) => {
let query = {};
if (req.query.client) {
@ -23,6 +32,23 @@ PermissionRoute.route("/")
let permission = await Permission.find(query);
res.json(permission);
}))
/**
* @api {post} /admin/permission
* @apiName AdminAddPermission
*
* @apiParam client The ID of the owning client
* @apiParam name Permission name
* @apiParam description A description, that makes it clear to the user, what this Permission allows to do
*
* @apiGroup admin_permission
* @apiPermission admin
*
* @apiSuccess {Object[]} permissions
* @apiSuccess {String} permissions._id The ID
* @apiSuccess {String} permissions.name Permission name
* @apiSuccess {String} permissions.description A description, that makes it clear to the user, what this Permission allows to do
* @apiSuccess {String} permissions.client The ID of the owning client
*/
.post(verify({
client: {
type: Types.STRING
@ -45,7 +71,19 @@ PermissionRoute.route("/")
});
await Permission.save(permission);
res.json(permission);
})).delete(promiseMiddleware(async (req, res) => {
}))
/**
* @api {delete} /admin/permission
* @apiName AdminDeletePermission
*
* @apiParam id The permission ID
*
* @apiGroup admin_permission
* @apiPermission admin
*
* @apiSuccess {Boolean} success
*/
.delete(promiseMiddleware(async (req, res) => {
let { id } = req.query;
await Permission.delete(id);
res.json({ success: true });

37
src/api/admin/regcode.ts
View File

@ -7,20 +7,49 @@ import { GetUserMiddleware } from "../middlewares/user";
import { HttpStatusCode } from "../../helper/request_error";
const RegCodeRoute: Router = Router();
RegCodeRoute.use(GetUserMiddleware(true, true), (req: Request, res, next) => {
if (!req.isAdmin) res.sendStatus(HttpStatusCode.FORBIDDEN)
else next()
});
RegCodeRoute.route("/")
/**
* @api {get} /admin/regcode
* @apiName AdminGetRegcodes
*
* @apiGroup admin_regcode
* @apiPermission admin
*
* @apiSuccess {Object[]} regcodes
* @apiSuccess {String} permissions._id The ID
* @apiSuccess {String} permissions.token The Regcode Token
* @apiSuccess {String} permissions.valid Defines if the Regcode is valid
* @apiSuccess {String} permissions.validTill Expiration date of RegCode
*/
.get(promiseMiddleware(async (req, res) => {
let regcodes = await RegCode.find({});
res.json(regcodes);
}))
/**
* @api {delete} /admin/regcode
* @apiName AdminDeleteRegcode
*
* @apiParam {String} id The id of the RegCode
*
* @apiGroup admin_regcode
* @apiPermission admin
*
* @apiSuccess {Boolean} success
*/
.delete(promiseMiddleware(async (req, res) => {
let { id } = req.query;
await RegCode.delete(id);
res.json({ success: true });
}))
/**
* @api {post} /admin/regcode
* @apiName AdminAddRegcode
*
* @apiGroup admin_regcode
* @apiPermission admin
*
* @apiSuccess {String} code The newly created code
*/
.post(promiseMiddleware(async (req, res) => {
let regcode = RegCode.new({
token: randomBytes(10).toString("hex"),

45
src/api/admin/user.ts
View File

@ -14,10 +14,37 @@ UserRoute.use(GetUserMiddleware(true, true), (req: Request, res, next) => {
})
UserRoute.route("/")
/**
* @api {get} /admin/user
* @apiName AdminGetUsers
*
* @apiGroup admin_user
* @apiPermission admin
* @apiSuccess {Object[]} user
* @apiSuccess {String} user._id The internal id of the user
* @apiSuccess {String} user.uid The public UID of the user
* @apiSuccess {String} user.username The username
* @apiSuccess {String} user.name The real name
* @apiSuccess {Date} user.birthday The birthday
* @apiSuccess {Number} user.gender 0 = none, 1 = male, 2 = female, 3 = other
* @apiSuccess {Boolean} user.admin Is admin or not
*/
.get(promiseMiddleware(async (req, res) => {
let users = await User.find({});
users.forEach(e => delete e.password && delete e.salt && delete e.encryption_key);
res.json(users);
}))
/**
* @api {delete} /admin/user
* @apiName AdminDeleteUser
*
* @apiParam {String} id The User ID
*
* @apiGroup admin_user
* @apiPermission admin
*
* @apiSuccess {Boolean} success
*/
.delete(promiseMiddleware(async (req, res) => {
let { id } = req.query;
let user = await User.findById(id);
@ -32,7 +59,23 @@ UserRoute.route("/")
await User.delete(user);
res.json({ success: true });
})).put(promiseMiddleware(async (req, res) => {
}))
/**
* @api {put} /admin/user
* @apiName AdminChangeUser
*
* @apiParam {String} id The User ID
*
* @apiGroup admin_user
* @apiPermission admin
*
* @apiSuccess {Boolean} success
*
* @apiDescription Flipps the user role:
* admin -> user
* user -> admin
*/
.put(promiseMiddleware(async (req, res) => {
let { id } = req.query;
let user = await User.findById(id);
user.admin = !user.admin;