DHBW-WE/MeetUp
5
0
Fork 0
Code Issues 7 Pull requests 5 Projects 1 Releases 5 Packages 1 Wiki Activity Actions 2

refactor(api): standardize Swagger documentation

Browse source
This commit is contained in:
Dominik 2025-06-17 22:11:22 +02:00
parent 16a5825dd3
commit 71a401ec9f
Signed by: dominik
GPG key ID: 06A4003FC5049644
7 changed files with 287 additions and 302 deletions
Download patch file Download diff file Expand all files Collapse all files

39
src/app/api/event/[eventID]/participant/[user]/route.ts
View file

@ -14,7 +14,7 @@ const patchParticipantSchema = z.object({
* summary: Get a specific participant's details in an event
* description: Returns the details of a specific participant in an event.
* tags:
* - Event_Participant
* - Event_Participant
* parameters:
* - in: path
* name: eventID
@ -39,13 +39,13 @@ const patchParticipantSchema = z.object({
* success:
* type: boolean
* participant:
* $ref: '#/components/schemas/Participant'
* $ref: "#/components/schemas/Participant"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -54,7 +54,7 @@ const patchParticipantSchema = z.object({
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -63,7 +63,7 @@ const patchParticipantSchema = z.object({
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User is not a participant or organizer of this event
@ -158,7 +158,7 @@ export const GET = auth(async (req, { params }) => {
* summary: Remove a participant from an event
* description: Removes a participant from an event. Only the organizer can remove participants.
* tags:
* - Event_Participant
* - Event_Participant
* parameters:
* - in: path
* name: eventID
@ -189,7 +189,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -198,7 +198,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -207,7 +207,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Only organizer can remove participants
@ -292,7 +292,7 @@ export const DELETE = auth(async (req, { params }) => {
* summary: Update a participant's status in an event
* description: Updates the status of a participant in an event. Only the participant can update their own status.
* tags:
* - Event_Participant
* - Event_Participant
* parameters:
* - in: path
* name: eventID
@ -328,22 +328,19 @@ export const DELETE = auth(async (req, { params }) => {
* success:
* type: boolean
* participant:
* $ref: '#/components/schemas/Participant'
* $ref: "#/components/schemas/Participant"
* 400:
* description: Bad request due to invalid input data.
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Invalid input data'
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -352,7 +349,7 @@ export const DELETE = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -361,7 +358,7 @@ export const DELETE = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Only participant can update their status

33
src/app/api/event/[eventID]/participant/route.ts
View file

@ -15,7 +15,7 @@ const postParticipantSchema = z.object({
* summary: Get participants of an event
* description: Returns all participants of a specific event.
* tags:
* - Event_Participant
* - Event_Participant
* parameters:
* - in: path
* name: eventID
@ -36,13 +36,13 @@ const postParticipantSchema = z.object({
* participants:
* type: array
* items:
* $ref: '#/components/schemas/Participant'
* $ref: "#/components/schemas/Participant"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -51,7 +51,7 @@ const postParticipantSchema = z.object({
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -60,7 +60,7 @@ const postParticipantSchema = z.object({
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User is not a participant or organizer of this event
@ -144,7 +144,7 @@ export const GET = auth(async (req, { params }) => {
* summary: Add a participant to an event
* description: Adds a user as a participant to a specific event.
* tags:
* - Event_Participant
* - Event_Participant
* parameters:
* - in: path
* name: eventID
@ -173,22 +173,19 @@ export const GET = auth(async (req, { params }) => {
* success:
* type: boolean
* participant:
* $ref: '#/components/schemas/Participant'
* $ref: "#/components/schemas/Participant"
* 400:
* description: Bad request due to invalid input data.
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Invalid input data'
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -197,7 +194,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -206,7 +203,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Only organizers can add participants
@ -215,7 +212,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User is already a participant of this event

37
src/app/api/event/[eventID]/route.ts
View file

@ -19,7 +19,7 @@ const patchEventSchema = z.object({
* summary: Get details of a specific event
* description: Returns the details of an event by its ID.
* tags:
* - Event
* - Event
* parameters:
* - in: path
* name: eventID
@ -38,13 +38,13 @@ const patchEventSchema = z.object({
* success:
* type: boolean
* event:
* $ref: '#/components/schemas/Event'
* $ref: "#/components/schemas/Event"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -53,7 +53,7 @@ const patchEventSchema = z.object({
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
*/
export const GET = auth(async (req, { params }) => {
if (!req.auth)
@ -140,7 +140,7 @@ export const GET = auth(async (req, { params }) => {
* summary: Delete a specific event
* description: Deletes an event by its ID if the user is the organizer.
* tags:
* - Event
* - Event
* parameters:
* - in: path
* name: eventID
@ -165,7 +165,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -174,7 +174,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: You are not the organizer of this event
@ -183,7 +183,7 @@ export const GET = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
*/
export const DELETE = auth(async (req, { params }) => {
if (!req.auth)
@ -251,7 +251,7 @@ export const DELETE = auth(async (req, { params }) => {
* summary: Update a specific event
* description: Updates an event by its ID if the user is the organizer.
* tags:
* - Event
* - Event
* parameters:
* - in: path
* name: eventID
@ -292,22 +292,19 @@ export const DELETE = auth(async (req, { params }) => {
* success:
* type: boolean
* event:
* $ref: '#/components/schemas/Event'
* $ref: "#/components/schemas/Event"
* 400:
* description: Bad request due to invalid input data.
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Invalid input data'
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -316,7 +313,7 @@ export const DELETE = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: You are not the organizer of this event
@ -325,7 +322,7 @@ export const DELETE = auth(async (req, { params }) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User or event not found

27
src/app/api/event/route.ts
View file

@ -22,7 +22,7 @@ const postEventSchema = z
* summary: Get all events for the authenticated user
* description: Returns all events where the user is an organizer or a participant.
* tags:
* - Event
* - Event
* responses:
* 200:
* description: List of events for the user.
@ -36,13 +36,13 @@ const postEventSchema = z
* events:
* type: array
* items:
* $ref: '#/components/schemas/Event'
* $ref: "#/components/schemas/Event"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -51,7 +51,7 @@ const postEventSchema = z
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found
@ -130,7 +130,7 @@ export const GET = auth(async (req) => {
* summary: Create a new event
* description: Creates a new event as the authenticated user (organizer).
* tags:
* - Event
* - Event
* requestBody:
* required: true
* content:
@ -165,22 +165,19 @@ export const GET = auth(async (req) => {
* success:
* type: boolean
* event:
* $ref: '#/components/schemas/Event'
* $ref: "#/components/schemas/Event"
* 400:
* description: Bad request due to invalid input data.
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Invalid input data'
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
* 401:
* description: Not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: Not authenticated
@ -189,7 +186,7 @@ export const GET = auth(async (req) => {
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: User not found

158
src/app/api/search/user/route.ts
View file

@ -17,85 +17,85 @@ const getSearchUserSchema = z.object({
/**
* @swagger
* /api/search/user:
* get:
* summary: Search for users
* description: Search for users by name, first name, or last name with pagination and sorting.
* tags:
* - Search
* parameters:
* - in: query
* name: query
* required: false
* schema:
* type: string
* description: The search query to filter users by name, first name, or last name.
* - in: query
* name: count
* required: false
* schema:
* type: integer
* description: The number of users to return per page (default is 10).
* - in: query
* name: page
* required: false
* schema:
* type: integer
* description: The page number to return (default is 1).
* - in: query
* name: sort_by
* required: false
* schema:
* type: string
* enum: ['created_at', 'name', 'first_name', 'last_name', 'id']
* description: The field to sort by (default is 'created_at').
* - in: query
* name: sort_order
* required: false
* schema:
* type: string
* enum: ['asc', 'desc']
* description: The order to sort by, either 'asc' or 'desc' (default is 'desc').
* responses:
* 200:
* description: Users found successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* users:
* type: array
* items:
* $ref: '#/components/schemas/PublicUser'
* count:
* type: integer
* description: The number of users returned.
* 400:
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ZodErrorResponse'
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Not authenticated'
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'User not found'
* get:
* summary: Search for users
* description: Search for users by name, first name, or last name with pagination and sorting.
* tags:
* - Search
* parameters:
* - in: query
* name: query
* required: false
* schema:
* type: string
* description: The search query to filter users by name, first name, or last name.
* - in: query
* name: count
* required: false
* schema:
* type: integer
* description: The number of users to return per page (default is 10).
* - in: query
* name: page
* required: false
* schema:
* type: integer
* description: The page number to return (default is 1).
* - in: query
* name: sort_by
* required: false
* schema:
* type: string
* enum: ["created_at", "name", "first_name", "last_name", "id"]
* description: The field to sort by (default is 'created_at').
* - in: query
* name: sort_order
* required: false
* schema:
* type: string
* enum: ["asc", "desc"]
* description: The order to sort by, either 'asc' or 'desc' (default is 'desc').
* responses:
* 200:
* description: Users found successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* users:
* type: array
* items:
* $ref: "#/components/schemas/PublicUser"
* count:
* type: integer
* description: The number of users returned.
* 400:
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "Not authenticated"
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "User not found"
*/
export const GET = auth(async function GET(req) {
if (!req.auth)

86
src/app/api/user/[user]/route.ts
View file

@ -5,49 +5,49 @@ import { prisma } from '@/prisma';
/**
* @swagger
* /api/user/{user}:
* get:
* summary: Get user information by ID or name
* description: Retrieve the information of a specific user by ID or name.
* tags:
* - User
* parameters:
* - in: path
* name: user
* required: true
* schema:
* type: string
* description: The ID or name of the user to retrieve.
* responses:
* 200:
* description: User information retrieved successfully.
* content:
* application/json:
* schema:
* type: 'object'
* properties:
* success:
* type: 'boolean'
* default: true
* user:
* $ref: '#/components/schemas/PublicUser'
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Not authenticated'
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'User not found'
* get:
* summary: Get user information by ID or name
* description: Retrieve the information of a specific user by ID or name.
* tags:
* - User
* parameters:
* - in: path
* name: user
* required: true
* schema:
* type: string
* description: The ID or name of the user to retrieve.
* responses:
* 200:
* description: User information retrieved successfully.
* content:
* application/json:
* schema:
* type: "object"
* properties:
* success:
* type: "boolean"
* default: true
* user:
* $ref: "#/components/schemas/PublicUser"
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "Not authenticated"
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "User not found"
*/
export const GET = auth(async function GET(req, { params }) {
if (!req.auth)

209
src/app/api/user/me/route.ts
View file

@ -21,42 +21,42 @@ const patchUserMeSchema = z.object({
/**
* @swagger
* /api/user/me:
* get:
* summary: Get the currently authenticated user's information
* description: Retrieve the information of the currently authenticated user.
* tags:
* - User
* responses:
* 200:
* description: User information retrieved successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* default: true
* user:
* $ref: '#/components/schemas/User'
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Not authenticated'
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'User not found'
* get:
* summary: Get the currently authenticated user's information
* description: Retrieve the information of the currently authenticated user.
* tags:
* - User
* responses:
* 200:
* description: User information retrieved successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* default: true
* user:
* $ref: "#/components/schemas/User"
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "Not authenticated"
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "User not found"
*/
export const GET = auth(async function GET(req) {
if (!req.auth)
@ -106,76 +106,73 @@ export const GET = auth(async function GET(req) {
/**
* @swagger
* /api/user/me:
* patch:
* summary: Update the currently authenticated user's information
* description: Update the information of the currently authenticated user.
* tags:
* - User
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* description: Username of the user.
* first_name:
* type: string
* description: First name of the user.
* last_name:
* type: string
* description: Last name of the user.
* email:
* type: string
* description: Email address of the user.
* image:
* type: string
* description: URL of the user's profile image.
* timezone:
* type: string
* description: Timezone of the user.
* responses:
* 200:
* description: User information updated successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* default: true
* user:
* $ref: '#/components/schemas/User'
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Not authenticated'
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'User not found'
* 400:
* description: Bad request due to invalid input data.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ErrorResponse'
* example:
* success: false
* message: 'Invalid input data'
* patch:
* summary: Update the currently authenticated user's information
* description: Update the information of the currently authenticated user.
* tags:
* - User
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* description: Username of the user.
* first_name:
* type: string
* description: First name of the user.
* last_name:
* type: string
* description: Last name of the user.
* email:
* type: string
* description: Email address of the user.
* image:
* type: string
* description: URL of the user's profile image.
* timezone:
* type: string
* description: Timezone of the user.
* responses:
* 200:
* description: User information updated successfully.
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* default: true
* user:
* $ref: "#/components/schemas/User"
* 401:
* description: User is not authenticated.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "Not authenticated"
* 404:
* description: User not found.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ErrorResponse"
* example:
* success: false
* message: "User not found"
* 400:
* description: Invalid request data.
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/ZodErrorResponse"
*/
export const PATCH = auth(async function PATCH(req) {
if (!req.auth)