docs: improve openapi data for password endpoints (#1938)

* docs: improve openapi data for password endpoints

* refactor: apply PR requested changes

---------

Co-authored-by: kim <kim.phanhoang@epfl.ch>

Author: pyphilia

src/services/auth/plugins/password/password.controller.ts

@@ -23,11 +23,11 @@ import {
   matchOne,
 } from '../passport';
 import {
-  getMembersCurrentPasswordStatus,
-  passwordLogin,
-  patchResetPasswordRequest,
-  postResetPasswordRequest,
-  setPassword,
+  createPassword,
+  getOwnPasswordStatus,
+  requestPasswordResetLink,
+  resetPassword,
+  signInWithPassword,
   updatePassword,
 } from './password.schemas';
 import { MemberPasswordService } from './password.service';
@@ -43,7 +43,7 @@ const plugin: FastifyPluginAsyncTypebox = async (fastify) => {
   fastify.post(
     '/login-password',
     {
-      schema: passwordLogin,
+      schema: signInWithPassword,
       preHandler: [
         captchaPreHandler(RecaptchaAction.SignInWithPassword, {
           shouldFail: false,
@@ -81,7 +81,7 @@ const plugin: FastifyPluginAsyncTypebox = async (fastify) => {
   fastify.post(
     '/password',
     {
-      schema: setPassword,
+      schema: createPassword,
       preHandler: [isAuthenticated, matchOne(validatedMemberAccountRole)],
     },
     async ({ user, body: { password } }, reply) => {
@@ -129,7 +129,7 @@ const plugin: FastifyPluginAsyncTypebox = async (fastify) => {
   fastify.post(
     '/password/reset',
     {
-      schema: postResetPasswordRequest,
+      schema: requestPasswordResetLink,
       preHandler: captchaPreHandler(RecaptchaAction.ResetPassword),
     },
     async (request, reply) => {
@@ -170,7 +170,7 @@ const plugin: FastifyPluginAsyncTypebox = async (fastify) => {
   fastify.patch(
     '/password/reset',
     {
-      schema: patchResetPasswordRequest,
+      schema: resetPassword,
       preHandler: authenticatePasswordReset,
     },
     async (request, reply) => {
@@ -206,7 +206,7 @@ const plugin: FastifyPluginAsyncTypebox = async (fastify) => {
   fastify.get(
     '/members/current/password/status',
     {
-      schema: getMembersCurrentPasswordStatus,
+      schema: getOwnPasswordStatus,
       preHandler: [isAuthenticated],
     },
     async ({ user }) => {

src/services/auth/plugins/password/password.schemas.ts

@@ -6,7 +6,8 @@ import type { FastifySchema } from 'fastify';
 import { customType } from '../../../../plugins/typebox';
 import { errorSchemaRef } from '../../../../schemas/global';
 
-export const passwordLogin = {
+export const signInWithPassword = {
+  operationId: 'signInWithPassword',
   tags: ['password'],
   summary: 'Log in with email and password',
   description:
@@ -20,9 +21,17 @@ export const passwordLogin = {
   querystring: customType.StrictObject({
     lang: Type.Optional(Type.String()),
   }),
+  response: {
+    [StatusCodes.OK]: customType.StrictObject({
+      resource: Type.String({ description: 'Redirection link' }),
+    }),
+    '4xx': errorSchemaRef,
+    '5xx': errorSchemaRef,
+  },
 } as const satisfies FastifySchema;
 
-export const setPassword = {
+export const createPassword = {
+  operationId: 'createPassword',
   tags: ['password'],
   summary: 'Set a password for the authenticated member',
   description:
@@ -38,6 +47,7 @@ export const setPassword = {
 } as const satisfies FastifySchema;
 
 export const updatePassword = {
+  operationId: 'updatePassword',
   tags: ['password'],
   summary: 'Update the password of the authenticated member',
   description:
@@ -55,7 +65,8 @@ export const updatePassword = {
   },
 } as const satisfies FastifySchema;
 
-export const postResetPasswordRequest = {
+export const requestPasswordResetLink = {
+  operationId: 'requestPasswordResetLink',
   tags: ['password'],
   summary: 'Create a reset password request',
   description:
@@ -70,7 +81,8 @@ export const postResetPasswordRequest = {
   },
 } as const satisfies FastifySchema;
 
-export const patchResetPasswordRequest = {
+export const resetPassword = {
+  operationId: 'resetPassword',
   tags: ['password'],
   summary: 'Confirm the reset password request',
   description:
@@ -85,7 +97,8 @@ export const patchResetPasswordRequest = {
   },
 } as const satisfies FastifySchema;
 
-export const getMembersCurrentPasswordStatus = {
+export const getOwnPasswordStatus = {
+  operationId: 'getOwnPasswordStatus',
   tags: ['password', 'current'],
   summary: 'Get the current password status of the authenticated member',
   description: 'Return whether the authenticated member has a password defined.',