From 50f2462eb9f5a49e1cc6cfb6ce8473b9804073f0 Mon Sep 17 00:00:00 2001
From: Nicolai Ort <info@nicolai-ort.com>
Date: Tue, 22 Dec 2020 19:23:35 +0100
Subject: [PATCH] Updated the openapi descriptions for all auth routes

ref #49
---
 src/controllers/AuthController.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/controllers/AuthController.ts b/src/controllers/AuthController.ts
index 2f571cb..cddb677 100644
--- a/src/controllers/AuthController.ts
+++ b/src/controllers/AuthController.ts
@@ -22,7 +22,7 @@ export class AuthController {
 	@ResponseSchema(UsernameOrEmailNeededError)
 	@ResponseSchema(PasswordNeededError)
 	@ResponseSchema(InvalidCredentialsError)
-	@OpenAPI({ description: 'Create a new access token object' })
+	@OpenAPI({ description: 'Login with your username/email and password. <br> You will receive: \n * access token (use it as a bearer token) \n * refresh token (will also be sent as a cookie)' })
 	async login(@Body({ validate: true }) createAuth: CreateAuth, @Res() response: any) {
 		let auth;
 		try {
@@ -42,7 +42,7 @@ export class AuthController {
 	@ResponseSchema(UsernameOrEmailNeededError)
 	@ResponseSchema(PasswordNeededError)
 	@ResponseSchema(InvalidCredentialsError)
-	@OpenAPI({ description: 'Create a new access token object', security: [{ "RefreshTokenCookie": [] }] })
+	@OpenAPI({ description: 'Logout using your refresh token. <br> This instantly invalidates all your access and refresh tokens.', security: [{ "RefreshTokenCookie": [] }] })
 	async logout(@Body({ validate: true }) handleLogout: HandleLogout, @CookieParam("lfk_backend__refresh_token") refresh_token: string, @Res() response: any) {
 		if (refresh_token && refresh_token.length != 0 && handleLogout.token == undefined) {
 			handleLogout.token = refresh_token;
@@ -65,7 +65,7 @@ export class AuthController {
 	@ResponseSchema(IllegalJWTError)
 	@ResponseSchema(UserNotFoundError)
 	@ResponseSchema(RefreshTokenCountInvalidError)
-	@OpenAPI({ description: 'refresh a access token', security: [{ "RefreshTokenCookie": [] }] })
+	@OpenAPI({ description: 'Refresh your access and refresh tokens using a valid refresh token. <br> You will receive: \n * access token (use it as a bearer token) \n * refresh token (will also be sent as a cookie)', security: [{ "RefreshTokenCookie": [] }] })
 	async refresh(@Body({ validate: true }) refreshAuth: RefreshAuth, @CookieParam("lfk_backend__refresh_token") refresh_token: string, @Res() response: any, @Req() req: any) {
 		if (refresh_token && refresh_token.length != 0 && refreshAuth.token == undefined) {
 			refreshAuth.token = refresh_token;
@@ -86,7 +86,7 @@ export class AuthController {
 	@ResponseSchema(Auth)
 	@ResponseSchema(UserNotFoundError)
 	@ResponseSchema(UsernameOrEmailNeededError)
-	@OpenAPI({ description: "Request a password reset token" })
+	@OpenAPI({ description: "Request a password reset token. <br> This will provide you with a reset token that you can use by posting to /api/auth/reset/{token}." })
 	async getResetToken(@Body({ validate: true }) passwordReset: CreateResetToken) {
 		//This really shouldn't just get returned, but sent via mail or sth like that. But for dev only this is fine.
 		return { "resetToken": await passwordReset.toResetToken() };
@@ -96,7 +96,7 @@ export class AuthController {
 	@ResponseSchema(Auth)
 	@ResponseSchema(UserNotFoundError)
 	@ResponseSchema(UsernameOrEmailNeededError)
-	@OpenAPI({ description: "Reset a user's password" })
+	@OpenAPI({ description: "Reset a user's utilising a valid password reset token. <br> This will set the user's password to the one you provided in the body. <br> To get a reset token post to /api/auth/reset with your username." })
 	async resetPassword(@Param("token") token: string, @Body({ validate: true }) passwordReset: ResetPassword) {
 		passwordReset.resetToken = token;
 		return await passwordReset.resetPassword();