From 89a6a90922df97ac7639ab22826b71413b838564 Mon Sep 17 00:00:00 2001
From: Oliwier Michalik <oliwier.michalik9@gmail.com>
Date: Thu, 26 Feb 2026 02:44:33 +0100
Subject: [PATCH 1/5] feat: implement custom apidoc generator that can handle
 vine, models and routes mostly automatically

---
 .idea/codeStyles/Project.xml        |   8 +
 app/controllers/auth_controller.ts  |  29 ++-
 app/models/user.ts                  |  10 +
 app/validators/auth.ts              |  12 +-
 app/validators/common.ts            |   6 +-
 app/validators/event.ts             |   8 +-
 app/validators/jury_member.ts       |   4 +-
 app/validators/organization.ts      |   8 +-
 app/validators/score.ts             |   6 +-
 app/validators/task.ts              |   6 +-
 app/validators/task_registration.ts |   2 +-
 app/validators/team.ts              |  10 +-
 commands/generate_spec.ts           |  45 ++++
 docs/generator/decorators.ts        |  79 +++++++
 docs/generator/index.ts             | 328 ++++++++++++++++++++++++++++
 docs/spec/openapi.json              |   1 +
 package.json                        |   5 +-
 pnpm-lock.yaml                      | 167 +++++++++-----
 start/routes.ts                     |  18 ++
 tsconfig.json                       |   2 +-
 20 files changed, 671 insertions(+), 83 deletions(-)
 create mode 100644 commands/generate_spec.ts
 create mode 100644 docs/generator/decorators.ts
 create mode 100644 docs/generator/index.ts
 create mode 100644 docs/spec/openapi.json

diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml
index 1107b67..b9a6ebf 100644
--- a/.idea/codeStyles/Project.xml
+++ b/.idea/codeStyles/Project.xml
@@ -1,5 +1,13 @@
 <component name="ProjectCodeStyleConfiguration">
   <code_scheme name="Project" version="173">
+    <TypeScriptCodeStyleSettings version="0">
+      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="false" />
+      <option name="FORCE_SEMICOLON_STYLE" value="true" />
+      <option name="USE_DOUBLE_QUOTES" value="false" />
+      <option name="FORCE_QUOTE_STYlE" value="true" />
+      <option name="ENFORCE_TRAILING_COMMA" value="WhenMultiline" />
+      <option name="SPACES_WITHIN_IMPORTS" value="true" />
+    </TypeScriptCodeStyleSettings>
     <codeStyleSettings language="JavaScript">
       <indentOptions>
         <option name="INDENT_SIZE" value="2" />
diff --git a/app/controllers/auth_controller.ts b/app/controllers/auth_controller.ts
index e90a2f8..fd8d3f0 100644
--- a/app/controllers/auth_controller.ts
+++ b/app/controllers/auth_controller.ts
@@ -23,15 +23,28 @@
 
 import User from '#models/user'
 import { UserGuard } from '#utils/permissions'
-import { loginValidator, registerValidator } from '#validators/auth'
+import { loginValidator, providerParamValidator, registerValidator } from '#validators/auth'
 import type { HttpContext } from '@adonisjs/core/http'
+import {
+  ApiOperation,
+  ApiRequest,
+  ApiResponse,
+} from '../../docs/generator/decorators.js'
 
 export default class AuthController {
-  public async redirect({ ally, params }: HttpContext) {
+  @ApiOperation({ description: 'Redirects to the social provider for authentication' })
+  @ApiRequest({ validator: providerParamValidator, withResponse: true })
+  @ApiResponse(307, { description: 'Redirects to the social provider' })
+  public async redirect({ ally, request }: HttpContext) {
+    const { params } = await request.validateUsing(providerParamValidator)
     return ally.use(params.provider).redirect()
   }
 
-  public async callback({ ally, auth, params, response }: HttpContext) {
+  @ApiOperation({ description: 'Handles the callback from the social provider' })
+  @ApiRequest({ validator: providerParamValidator, withResponse: true })
+  @ApiResponse(307, { description: 'Redirects to the status page' })
+  public async callback({ ally, auth, request, response }: HttpContext) {
+    const { params } = await request.validateUsing(providerParamValidator)
     const provider = ally.use(params.provider)
 
     // Handle common OAuth errors
@@ -51,7 +64,7 @@ export default class AuthController {
       {
         email: socialUser.email,
         nickname: socialUser.nickName || socialUser.name || socialUser.email.split('@')[0],
-        // name and surname are kept as null and will be overriten later
+        // name and surname are kept as null and will be overridden later
         avatarUrl: socialUser.avatarUrl,
         password: null,
         permissions: UserGuard.build(), // TODO: Combine into constant of BASE_PERMISSIONS or sth idk
@@ -65,6 +78,9 @@ export default class AuthController {
     return response.redirect('/status')
   }
 
+  @ApiOperation({ description: 'Registers a new user with email and password' })
+  @ApiRequest({ validator: registerValidator, withResponse: true })
+  @ApiResponse(201, { description: 'User registered successfully', data: User })
   public async register({ request, auth, response }: HttpContext) {
     // Validate the input (email, password, etc.)
     const payload = await request.validateUsing(registerValidator)
@@ -82,6 +98,9 @@ export default class AuthController {
     return response.created({ message: 'Registration successful', user })
   }
 
+  @ApiOperation({ description: 'Logs in a user with email and password' })
+  @ApiRequest({ validator: loginValidator, withResponse: true })
+  @ApiResponse(200, { description: 'User logged in successfully', data: User })
   public async login({ request, auth, response }: HttpContext) {
     const { email, password } = await request.validateUsing(loginValidator)
     const user = await User.findBy('email', email)
@@ -98,6 +117,8 @@ export default class AuthController {
     return response.ok({ message: 'Login successful', user: validatedUser })
   }
 
+  @ApiOperation({ description: 'Logs out the current user' })
+  @ApiResponse(200, { description: 'User logged out successfully' })
   public async logout({ auth, response }: HttpContext) {
     await auth.use('web').logout()
     return response.redirect('/')
diff --git a/app/models/user.ts b/app/models/user.ts
index 59c249b..8da7c8c 100644
--- a/app/models/user.ts
+++ b/app/models/user.ts
@@ -27,6 +27,7 @@ import { compose } from '@adonisjs/core/helpers'
 import { BaseModel, column } from '@adonisjs/lucid/orm'
 import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
 import type { UserPermissions, Mask } from '#utils/permissions'
+import { ApiColumn } from '../../docs/generator/decorators.js'
 
 const AuthFinder = withAuthFinder(() => hash.use('scrypt'), {
   uids: ['email'],
@@ -35,32 +36,41 @@ const AuthFinder = withAuthFinder(() => hash.use('scrypt'), {
 
 export default class User extends compose(BaseModel, AuthFinder) {
   @column({ isPrimary: true })
+  @ApiColumn(Number)
   declare id: number
 
   @column()
+  @ApiColumn(String, { example: 'JohnnyBravo' })
   declare nickname: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'John' })
   declare name: string | null
 
   @column()
+  @ApiColumn(String, { required: false, example: 'Bravo' })
   declare surname: string | null
 
   @column()
+  @ApiColumn(String, { example: 'johnny.bravo@example.com' })
   declare email: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'https://example.com/avatar.png' })
   declare avatarUrl: string | null
 
   @column()
+  @ApiColumn(Number, { format: 'binary' })
   declare permissions: Mask<typeof UserPermissions>
 
   @column({ serializeAs: null })
   declare password: string | null
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 }
diff --git a/app/validators/auth.ts b/app/validators/auth.ts
index 90bda23..863e9e9 100644
--- a/app/validators/auth.ts
+++ b/app/validators/auth.ts
@@ -23,7 +23,15 @@
 
 import vine from '@vinejs/vine'
 
-export const registerValidator = vine.compile(
+export const providerParamValidator = vine.create(
+  vine.object({
+    params: vine.object({
+      provider: vine.enum(['discord', 'github']),
+    }),
+  }),
+)
+
+export const registerValidator = vine.create(
   vine.object({
     nickname: vine.string().trim().minLength(3).maxLength(16),
     name: vine.string().trim().minLength(3).maxLength(32).optional(),
@@ -36,7 +44,7 @@ export const registerValidator = vine.compile(
   }),
 )
 
-export const loginValidator = vine.compile(
+export const loginValidator = vine.create(
   vine.object({
     email: vine.string().email().trim(),
     password: vine.string(),
diff --git a/app/validators/common.ts b/app/validators/common.ts
index dbc2562..3ffa5bf 100644
--- a/app/validators/common.ts
+++ b/app/validators/common.ts
@@ -39,7 +39,7 @@ async function matchesConfirmation(value: unknown, _options: any, field: FieldCo
 }
 const matchesConfirmationRule = vine.createRule(matchesConfirmation)
 
-export const confirmationValidator = vine.compile(
+export const confirmationValidator = vine.create(
   vine.object({
     confirmation: vine.string().use(matchesConfirmationRule()),
   }),
@@ -73,9 +73,9 @@ export const commonQuerySchema = vine.object({
     .optional(),
 })
 
-export const commonQueryValidator = vine.compile(commonQuerySchema)
+export const commonQueryValidator = vine.create(commonQuerySchema)
 
-export const paramsIdValidator = vine.compile(
+export const paramsIdValidator = vine.create(
   vine.object({
     params: vine.object({
       id: vine.string().uuid(),
diff --git a/app/validators/event.ts b/app/validators/event.ts
index 0c4fd83..e1c40e9 100644
--- a/app/validators/event.ts
+++ b/app/validators/event.ts
@@ -35,7 +35,7 @@ const eventSchema = {
   maxTeamSize: vine.number().min(1),
 }
 
-export const createEventValidator = vine.compile(
+export const createEventValidator = vine.create(
   vine.object({
     ...eventSchema,
     slug: vine.string().trim().toLowerCase().regex(/^[a-z0-9-]+$/).use(notUUIDv4()).unique(async (db, value) => {
@@ -45,7 +45,7 @@ export const createEventValidator = vine.compile(
   }),
 )
 
-export const updateEventValidator = vine.compile(
+export const updateEventValidator = vine.create(
   vine.object({
     ...partialSchema(eventSchema), // Is there a standard way to get partial object in vine?
     slug: vine.string().unique(async (db, value, field) => {
@@ -60,14 +60,14 @@ export const updateEventValidator = vine.compile(
   }),
 )
 
-export const storeAdministratorValidator = vine.compile(
+export const storeAdministratorValidator = vine.create(
   vine.object({
     userId: vine.number().positive(),
     permissions: vine.number().min(0).optional(),
   }),
 )
 
-export const updateAdministratorValidator = vine.compile(
+export const updateAdministratorValidator = vine.create(
   vine.object({
     permissions: vine.number().min(0),
   }),
diff --git a/app/validators/jury_member.ts b/app/validators/jury_member.ts
index 31b8e1a..d9b7942 100644
--- a/app/validators/jury_member.ts
+++ b/app/validators/jury_member.ts
@@ -32,7 +32,7 @@ const juryMemberSchema = {
  * Validator to validate the payload when creating
  * a new jury member.
  */
-export const createJuryMemberValidator = vine.compile(
+export const createJuryMemberValidator = vine.create(
   vine.object({
     ...juryMemberSchema,
     userId: vine.number().positive(),
@@ -43,6 +43,6 @@ export const createJuryMemberValidator = vine.compile(
  * Validator to validate the payload when updating
  * an existing jury member.
  */
-export const updateJuryMemberValidator = vine.compile(
+export const updateJuryMemberValidator = vine.create(
   vine.object(juryMemberSchema),
 )
diff --git a/app/validators/organization.ts b/app/validators/organization.ts
index c05e4ac..79e0680 100644
--- a/app/validators/organization.ts
+++ b/app/validators/organization.ts
@@ -34,7 +34,7 @@ const organizationSchema = {
  * Validator to validate the payload when creating
  * a new organization.
  */
-export const createOrganizationValidator = vine.compile(
+export const createOrganizationValidator = vine.create(
   vine.object(organizationSchema),
 )
 
@@ -42,12 +42,12 @@ export const createOrganizationValidator = vine.compile(
  * Validator to validate the payload when updating
  * an existing organization.
  */
-export const updateOrganizationValidator = vine.compile(
+export const updateOrganizationValidator = vine.create(
   vine.object(organizationSchema),
 )
 
-export const createSponsorValidator = vine.compile(
+export const createSponsorValidator = vine.create(
   vine.object({
     organizationId: vine.string().uuid(),
   }),
-)
\ No newline at end of file
+)
diff --git a/app/validators/score.ts b/app/validators/score.ts
index 5928224..d7685fc 100644
--- a/app/validators/score.ts
+++ b/app/validators/score.ts
@@ -30,16 +30,16 @@ const scoringCriterionCoreSchema = {
   weight: vine.number().positive().min(0).max(100),
 }
 
-export const createScoringCriterionValidator = vine.compile(
+export const createScoringCriterionValidator = vine.create(
   vine.object({
     ...scoringCriterionCoreSchema,
     description: vine.string().trim().escape().nullable().optional(),
   }),
 )
 
-export const updateScoringCriterionValidator = vine.compile(
+export const updateScoringCriterionValidator = vine.create(
   vine.object({
     ...partialSchema(scoringCriterionCoreSchema),
     description: vine.string().trim().escape().nullable().optional(),
   }),
-)
\ No newline at end of file
+)
diff --git a/app/validators/task.ts b/app/validators/task.ts
index c768f84..6dba5e6 100644
--- a/app/validators/task.ts
+++ b/app/validators/task.ts
@@ -42,7 +42,7 @@ const taskDateFields = () => ({
   submissionsEndAt: vine.date({ formats: { utc: true } }).afterField('submissionsStartAt').nullable().optional(),
 })
 
-export const createTaskValidator = vine.compile(
+export const createTaskValidator = vine.create(
   vine.object({
     ...taskCoreSchema,
     status: vine.enum(['DRAFT', 'ACTIVE', 'ARCHIVED'] as const).optional(),
@@ -57,13 +57,13 @@ export const createTaskValidator = vine.compile(
   }),
 )
 
-export const updateHackathonTaskValidator = vine.compile(
+export const updateHackathonTaskValidator = vine.create(
   vine.object({
     requirementsDocumentUrl: vine.string().trim().url(),
   }),
 )
 
-export const updateTaskValidator = vine.compile(
+export const updateTaskValidator = vine.create(
   vine.object({
     ...partialSchema(taskCoreSchema),
     slug: vine.string().trim().toLowerCase().regex(/^[a-z0-9-]+$/).use(notUUIDv4()).unique(async (db, value, field) => {
diff --git a/app/validators/task_registration.ts b/app/validators/task_registration.ts
index 3434522..389f292 100644
--- a/app/validators/task_registration.ts
+++ b/app/validators/task_registration.ts
@@ -31,6 +31,6 @@ const TaskRegistrationSchema = {
  * Validator to validate the payload when creating
  * a new task registration.
  */
-export const createTaskRegistrationValidator = vine.compile(
+export const createTaskRegistrationValidator = vine.create(
   vine.object(TaskRegistrationSchema),
 )
diff --git a/app/validators/team.ts b/app/validators/team.ts
index a44bf02..39f1123 100644
--- a/app/validators/team.ts
+++ b/app/validators/team.ts
@@ -28,7 +28,7 @@ import { invitationValidity } from '#utils/teams'
 const teamSchema = {
 }
 
-export const createTeamValidator = vine.compile(
+export const createTeamValidator = vine.create(
   vine.object({
     ...teamSchema,
     name: vine.string().trim().unique(async (db, value, field) => {
@@ -40,7 +40,7 @@ export const createTeamValidator = vine.compile(
   }),
 )
 
-export const updateTeamValidator = vine.compile(
+export const updateTeamValidator = vine.create(
   vine.object({
     ...partialSchema(teamSchema),
     name: vine.string().trim().unique(async (db, value, field) => {
@@ -53,7 +53,7 @@ export const updateTeamValidator = vine.compile(
   }),
 )
 
-export const kickMemberValidator = vine.compile(
+export const kickMemberValidator = vine.create(
   vine.object({
     member: vine.string().uuid(),
     params: vine.object({
@@ -62,14 +62,14 @@ export const kickMemberValidator = vine.compile(
   }),
 )
 
-export const teamInvitationValidator = vine.compile(
+export const teamInvitationValidator = vine.create(
   vine.object({
     email: vine.string().email().trim().optional(),
     validFor: vine.enum(Object.keys(invitationValidity)),
   }),
 )
 
-export const teamInvitationResponseValidator = vine.compile(
+export const teamInvitationResponseValidator = vine.create(
   vine.object({
     action: vine.enum(['ACCEPT', 'REJECT']).optional(),
     params: vine.object({
diff --git a/commands/generate_spec.ts b/commands/generate_spec.ts
new file mode 100644
index 0000000..5dc67c9
--- /dev/null
+++ b/commands/generate_spec.ts
@@ -0,0 +1,45 @@
+/*
+ *          ______            __            __
+ *    _  __/ ____/___  ____  / /____  _____/ /_
+ *   | |/_/ /   / __ \/ __ \/ __/ _ \/ ___/ __/
+ *  _>  </ /___/ /_/ / / / / /_/  __(__  ) /_
+ * /_/|_|\____/\____/_/ /_/\__/\___/____/\__/
+ *     Copyright (C) 2026 xContest Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/.
+ *
+ */
+
+import { BaseCommand } from '@adonisjs/core/ace'
+import type { CommandOptions } from '@adonisjs/core/types/ace'
+import app from '@adonisjs/core/services/app'
+import { generateApiSpec } from '../docs/generator/index.js'
+import * as fs from 'node:fs'
+import path from 'node:path'
+
+export default class GenerateSpec extends BaseCommand {
+  static commandName = 'generate:spec'
+  static description = ''
+
+  static options: CommandOptions = {}
+
+  async run() {
+    await app.boot()
+    await app.start(() => {})
+    await app.ready(() => {})
+
+    const spec = await generateApiSpec()
+    fs.writeFileSync(path.join(import.meta.dirname, '../docs/spec/openapi.json'), spec.getSpecAsJson())
+  }
+}
diff --git a/docs/generator/decorators.ts b/docs/generator/decorators.ts
new file mode 100644
index 0000000..fadfd68
--- /dev/null
+++ b/docs/generator/decorators.ts
@@ -0,0 +1,79 @@
+/*
+ *          ______            __            __
+ *    _  __/ ____/___  ____  / /____  _____/ /_
+ *   | |/_/ /   / __ \/ __ \/ __/ _ \/ ___/ __/
+ *  _>  </ /___/ /_/ / / / / /_/  __(__  ) /_
+ * /_/|_|\____/\____/_/ /_/\__/\___/____/\__/
+ *     Copyright (C) 2026 xContest Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/.
+ *
+ */
+
+import 'reflect-metadata'
+import type { VineValidator } from '@vinejs/vine'
+import type { BaseModel } from '@adonisjs/lucid/orm'
+import type { SchemaObjectFormat } from 'openapi3-ts/oas30'
+
+const makeMetaDecorator = <Args extends any[]>(tag: string, transformArgs: (args: Args) => any = (a) => a[0], acceptClass: boolean = false) =>
+  (...args: Args) => (target: any, propertyKey?: string | symbol) => {
+    if (propertyKey)
+      Reflect.defineMetadata(tag, transformArgs(args), target, propertyKey) // Method Decorator
+    else
+      if (acceptClass)
+        Reflect.defineMetadata(tag, transformArgs(args), target) // Class Decorator
+      else
+        throw new Error(`Decorator ${tag} can only be applied to methods`)
+  }
+
+export const ApiTag = makeMetaDecorator<[string, string?]>('spec:tag', ([name, description]) => ({ name, description }), true)
+
+export interface ApiOperationOptions {
+  summary?: string
+  description?: string
+  deprecated?: boolean
+}
+export const ApiOperation = makeMetaDecorator<[ApiOperationOptions]>('spec:operation')
+
+export type ApiRequestOptions = {
+  validator: VineValidator<any, any>,
+  withResponse?: boolean
+} // TODO: Add support for custom request data if necessary in the future
+export const ApiRequest = makeMetaDecorator<[ApiRequestOptions]>('spec:requestBody')
+
+export type PrimitiveResponseDataType = typeof BaseModel | object
+export type ResponseDataType = PrimitiveResponseDataType | [PrimitiveResponseDataType]
+
+export type ApiResponseOptions = {
+  description?: string,
+  data?: ResponseDataType
+}
+export type ApiResponseData = ApiResponseOptions & { status: number }
+export const ApiResponse = (status: number, options: ApiResponseOptions) =>
+  (target: any, propertyKey: string | symbol) => {
+    if (!propertyKey)
+      throw new Error('Decorator ApiResponse can only be applied to methods')
+
+    const current = Reflect.getMetadata('spec:responses', target, propertyKey) ?? []
+    Reflect.defineMetadata('spec:responses', [...current, { status: status, ...options }], target, propertyKey)
+  }
+
+export type ApiColumnOptions = {
+  format?: SchemaObjectFormat,
+  example?: any,
+  description?: string,
+  required?: boolean,
+  hidden?: boolean,
+}
+export const ApiColumn = makeMetaDecorator<[ResponseDataType, ApiColumnOptions?]>('spec:column', ([type, options]) => ({ type, ...options }))
diff --git a/docs/generator/index.ts b/docs/generator/index.ts
new file mode 100644
index 0000000..f006404
--- /dev/null
+++ b/docs/generator/index.ts
@@ -0,0 +1,328 @@
+/*
+ *          ______            __            __
+ *    _  __/ ____/___  ____  / /____  _____/ /_
+ *   | |/_/ /   / __ \/ __ \/ __/ _ \/ ___/ __/
+ *  _>  </ /___/ /_/ / / / / /_/  __(__  ) /_
+ * /_/|_|\____/\____/_/ /_/\__/\___/____/\__/
+ *     Copyright (C) 2026 xContest Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/.
+ *
+ */
+
+/* eslint-disable no-console */
+
+import app from '@adonisjs/core/services/app'
+import type { HttpRouterService } from '@adonisjs/core/types'
+import type { OperationObject, PathItemObject, ResponsesObject, SchemaObject, TagObject } from 'openapi3-ts/oas31'
+import { OpenApiBuilder } from 'openapi3-ts/oas31'
+import useColors from '@poppinss/colors'
+import type {
+  ApiColumnOptions,
+  ApiOperationOptions,
+  ApiRequestOptions,
+  ApiResponseData,
+  ResponseDataType,
+} from './decorators.js'
+import type { VineAny } from '@vinejs/vine'
+import vine from '@vinejs/vine'
+import { BaseModel } from '@adonisjs/lucid/orm'
+import type { ColumnOptions } from '@adonisjs/lucid/types/model'
+import { DateTime } from 'luxon'
+
+const colors = useColors.ansi()
+
+type Route = ReturnType<HttpRouterService['toJSON']>['root'][number]
+type RouteHandler = Route['handler']
+
+type PartialOperation = Promise<Partial<OperationObject>>
+
+let IS_SILENT = false
+const log = (...args: any[]) => {
+  if (!IS_SILENT)
+    console.log(...args)
+}
+
+// Gets api tag for a route handler.
+// It first checks for a tag on controller method, then controller class,
+// and finally falls back to using the controller name without 'Controller' suffix.
+const getApiTagFor = async (handler: RouteHandler): Promise<TagObject> => {
+  if ('reference' in handler) {
+    // @ts-ignore
+    // eslint-disable-next-line @unicorn/no-await-expression-member
+    const handlerClass = (await handler.reference[0]()).default
+    return Reflect.getMetadata('spec:tag', handlerClass.prototype, handler.reference[1])
+      ?? Reflect.getMetadata('spec:tag', handlerClass)
+      ?? { name: handlerClass.name.split('Controller')[0], description: `Endpoints provided by ${handlerClass.name}` }
+  } else
+    return { name: 'Default', description: 'Default tag for all non-classified endpoints' }
+}
+
+// Gets meta tag for a route handler.
+const getMetaTag = async <T>(handler: RouteHandler, key: string): Promise<T | null> => {
+  if ('reference' in handler) {
+    // @ts-ignore
+    // eslint-disable-next-line @unicorn/no-await-expression-member
+    const handlerClass = (await handler.reference[0]()).default
+    return Reflect.getMetadata(key, handlerClass.prototype, handler.reference[1]) ?? null
+  } else
+    return null
+}
+
+// Gets operation id for a route handler.
+// Operation id is a combination of the controller name and method name.
+// If the above method fails, it generates operation id based on the route pattern.
+const getOperationIdFor = (handler: RouteHandler, pattern: string): string => {
+  if ('reference' in handler)
+    // @ts-ignore
+    return `${handler.reference[0].name}.${handler.reference[1]}`
+  else
+    return `global${pattern === '/' ? '.index' : pattern.replace('/', '.')}`
+}
+
+// Replaces an Adonis pattern with the OpenAPI path. (e.g. '/users/:id' -> '/users/{id}')
+const convertPatternToPath = (pattern: string) =>
+  pattern.replace(/:([a-zA-Z]+)/g, '{$1}')
+
+// Generate basic data for an operation.
+// This includes summary, description, and deprecated status.
+const generateOperationData = async (route: Route): PartialOperation => {
+  const operation = await getMetaTag<ApiOperationOptions>(route.handler, 'spec:operation')
+  return (operation ?? {}) as PartialOperation
+}
+
+// Generate request data for an operation.
+// This includes parameters and request body schema.
+const generateRequestData = async (route: Route): Promise<PartialOperation> => {
+  const requestBody = await getMetaTag<ApiRequestOptions>(route.handler, 'spec:requestBody')
+  if (!requestBody)
+    return {}
+
+  const data: Partial<OperationObject> = {
+    parameters: [], // This function is called before parameters are generated.
+  }
+
+  if ('validator' in requestBody) {
+    const validator = requestBody.validator
+    const properties = validator.schema.getProperties()
+
+    // Take params from the validator
+    const { params, ...rest } = properties
+    const paramsObj = params ? params.getProperties() : {}
+
+    for (const [key, value] of Object.entries(paramsObj as Record<string, VineAny>))
+      data.parameters!.push({
+        name: key,
+        in: 'path',
+        required: true,
+        schema: value.toJSONSchema() as SchemaObject,
+      })
+
+    if (rest && Object.keys(rest).length > 0) {
+      const restObj = vine.object(rest)
+
+      data.requestBody = {
+        content: {
+          'application/json': {
+            schema: restObj.toJSONSchema() as SchemaObject,
+          },
+        },
+      }
+    }
+  }
+
+  return data
+}
+
+// Generate SchemaObject from either a Vine validator or Lucid model
+const generateSchemaForDataType = (schemas: { [key: string]: SchemaObject }, data: ApiResponseData['data']): SchemaObject | undefined => {
+  if (!data)
+    return undefined
+
+  if (Array.isArray(data))
+    return {
+      type: 'array',
+      items: generateSchemaForDataType(schemas, data[0]),
+    }
+  // @ts-ignore
+  else if (data.prototype instanceof BaseModel) {
+    // @ts-ignore
+    const modelName = data.name
+    if (schemas[modelName])
+      return { $ref: `#/components/schemas/${modelName}` }
+    // @ts-ignore
+    const columnsDefinitions: Map<string, ColumnOptions> = data.$columnsDefinitions
+
+    const requiredFields: string[] = []
+    schemas[modelName] = {
+      type: 'object',
+      properties: Object.fromEntries(columnsDefinitions.entries().map(([column, options]) => {
+        if (options.serializeAs === null)
+          return null
+
+        // @ts-ignore
+        const columnData = Reflect.getMetadata('spec:column', data.prototype, column) as ApiColumnOptions & {
+          type: ResponseDataType
+        }
+        if (columnData?.hidden)
+          return null
+
+        if (!columnData?.type) {
+          // @ts-ignore
+          log(colors.yellow(`  ! Couldn't infer type for column ${column} on model for table ${data.table}. Please add @ApiColumn decorator to the column in question.`))
+          return null
+        }
+
+        const baseType: Partial<SchemaObject>
+          = generateSchemaForDataType(schemas, columnData.type) ?? {
+            type: 'null',
+            description: 'Failed to infer (override)',
+          }
+
+        if (columnData.required ?? true)
+          requiredFields.push(column)
+
+        return [
+          column,
+          {
+            description: columnData?.description,
+            format: columnData?.format,
+            example: columnData?.example,
+            ...baseType,
+          },
+        ]
+      }).filter((obj) => !!obj)),
+      required: requiredFields,
+    }
+    return { $ref: `#/components/schemas/${modelName}` }
+  } else if ('toJSONSchema' in data && typeof data.toJSONSchema === 'function')
+    return data.toJSONSchema() as SchemaObject
+  else if (data === Number)
+    return { type: 'number' }
+  else if (data === String)
+    return { type: 'string' }
+  else if (data === Object)
+    return { type: 'object' }
+  else if (data === Boolean)
+    return { type: 'boolean' }
+  else if (data === Date)
+    return { type: 'string', format: 'date' }
+  else if (data === DateTime)
+    return { type: 'string', format: 'date-time' }
+  else
+    throw new Error(`Unsupported data type for response body: ${typeof data}`)
+}
+
+// Generate response data for an operation.
+// This includes status codes, headers, and content.
+const generateResponseData = async (schemas: { [key: string]: SchemaObject }, route: Route): Promise<PartialOperation> => {
+  const responses: ResponsesObject = {}
+  const responseData = await getMetaTag<ApiResponseData[]>(route.handler, 'spec:responses')
+  if (!responseData)
+    return {}
+
+  // Special case for ApiRequest with withResponse option on validator
+  const request = await getMetaTag<ApiRequestOptions>(route.handler, 'spec:requestBody')
+  if (request && 'validator' in request && request.withResponse) {
+    if (!schemas['ValidationError'])
+      schemas['ValidationError'] = vine
+        .object({
+          errors: vine.array(
+            vine.object({
+              message: vine.string(),
+              rule: vine.string(),
+              field: vine.string(),
+            }),
+          ),
+        })
+        .toJSONSchema() as SchemaObject
+    responses[422] = {
+      description: 'Provided request data did not pass validation',
+      content: {
+        'application/json': {
+          schema: {
+            $ref: '#/components/schemas/ValidationError',
+          },
+        },
+      },
+    }
+  }
+
+  for (const response of responseData) {
+    const { status, description, data } = response
+    const responseSchema = generateSchemaForDataType(schemas, data)
+    responses[status] = {
+      description: description,
+      content: responseSchema ? { 'application/json': responseSchema ? {
+        schema: responseSchema,
+      } : undefined } : undefined,
+    }
+  }
+
+  return { responses }
+}
+
+// Automatically generate OpenApi3 spec from decorators on Adonis controllers.
+export const generateApiSpec = async (config?: { silent?: boolean }) => {
+  IS_SILENT = config?.silent ?? false
+  log(colors.yellow('Generating OpenAPI spec...'))
+  const server = await app.container.make('server')
+  await server.boot()
+  const router = await app.container.make('router')
+
+  const tags: Record<string, TagObject> = {}
+  const operations: { [key: string]: PathItemObject } = {}
+  const schemas: { [key: string]: SchemaObject } = {}
+
+  for (const route of router.toJSON().root) {
+    log(colors.gray(`❯ Processing route ${route.pattern}`))
+    const apiTag = await getApiTagFor(route.handler)
+    tags[apiTag.name] = apiTag
+
+    const path = convertPatternToPath(route.pattern)
+
+    if (!operations[path])
+      operations[path] = {}
+    for (const method of route.methods.filter((m) => m !== 'HEAD')) {
+      Object.assign(operations[path], {
+        [method.toLowerCase()]: {
+          operationId: getOperationIdFor(route.handler, route.pattern),
+          tags: [apiTag.name],
+
+          ...(await generateOperationData(route)),
+          ...(await generateResponseData(schemas, route)),
+          ...(await generateRequestData(route)),
+        },
+      })
+
+      if (route.middleware.all().values().some((mwr) => mwr.name === 'auth')) {
+        const pathObject = operations[path][method.toLowerCase() as keyof PathItemObject] as OperationObject
+        pathObject.security = [{ session: [] }]
+      }
+    }
+
+    log(colors.green('  ✔') + colors.gray(' Gathered data for route.'))
+  }
+
+  const builder = OpenApiBuilder.create()
+  builder.addSecurityScheme('session', {
+    type: 'apiKey',
+    in: 'cookie',
+    name: 'xcontest-session',
+  })
+  Object.values(tags).forEach((tag) => builder.addTag(tag))
+  Object.entries(schemas).forEach(([name, schema]) => builder.addSchema(name, schema))
+  Object.entries(operations).forEach(([path, operation]) => builder.addPath(path, operation))
+  return builder
+}
diff --git a/docs/spec/openapi.json b/docs/spec/openapi.json
new file mode 100644
index 0000000..78ccf22
--- /dev/null
+++ b/docs/spec/openapi.json
@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}}}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"]},"post":{"operationId":"EventsController.store","tags":["Events"]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"]},"put":{"operationId":"EventsController.update","tags":["Events"]},"patch":{"operationId":"EventsController.update","tags":["Events"]},"delete":{"operationId":"EventsController.destroy","tags":["Events"]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"]},"patch":{"operationId":"TeamsController.update","tags":["Teams"]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"]},"patch":{"operationId":"TasksController.update","tags":["Tasks"]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
diff --git a/package.json b/package.json
index d628f2e..6dbd8c6 100644
--- a/package.json
+++ b/package.json
@@ -66,8 +66,11 @@
     "@adonisjs/session": "^7.7.1",
     "@aws-sdk/client-s3": "^3.995.0",
     "@aws-sdk/s3-request-presigner": "^3.995.0",
-    "@vinejs/vine": "^3.0.1",
+    "@poppinss/colors": "^4.1.6",
+    "@scalar/core": "^0.3.42",
+    "@vinejs/vine": "^4.3.0",
     "luxon": "^3.7.2",
+    "openapi3-ts": "^4.5.0",
     "pg": "^8.18.0",
     "reflect-metadata": "^0.2.2"
   },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3d1a764..7a2e265 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -10,40 +10,49 @@ importers:
     dependencies:
       '@adonisjs/ally':
         specifier: ^5.1.1
-        version: 5.1.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))
+        version: 5.1.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))
       '@adonisjs/auth':
         specifier: ^9.4.0
-        version: 9.6.0(9caa50a3b3df7d7047d71e59d2399cfb)
+        version: 9.6.0(34f7b8323dd7e033f83e16958dfe5221)
       '@adonisjs/bouncer':
         specifier: ^3.1.6
-        version: 3.1.6(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))
+        version: 3.1.6(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))
       '@adonisjs/core':
         specifier: ^6.18.0
-        version: 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+        version: 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       '@adonisjs/cors':
         specifier: ^2.2.1
-        version: 2.2.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))
+        version: 2.2.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))
       '@adonisjs/drive':
         specifier: ^3.4.1
-        version: 3.4.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@aws-sdk/client-s3@3.995.0)(@aws-sdk/s3-request-presigner@3.995.0)
+        version: 3.4.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@aws-sdk/client-s3@3.995.0)(@aws-sdk/s3-request-presigner@3.995.0)
       '@adonisjs/lucid':
         specifier: ^21.6.1
-        version: 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0)
+        version: 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0)
       '@adonisjs/session':
         specifier: ^7.7.1
-        version: 7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))
+        version: 7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))
       '@aws-sdk/client-s3':
         specifier: ^3.995.0
         version: 3.995.0
       '@aws-sdk/s3-request-presigner':
         specifier: ^3.995.0
         version: 3.995.0
+      '@poppinss/colors':
+        specifier: ^4.1.6
+        version: 4.1.6
+      '@scalar/core':
+        specifier: ^0.3.42
+        version: 0.3.42
       '@vinejs/vine':
-        specifier: ^3.0.1
-        version: 3.0.1
+        specifier: ^4.3.0
+        version: 4.3.0
       luxon:
         specifier: ^3.7.2
         version: 3.7.2
+      openapi3-ts:
+        specifier: ^4.5.0
+        version: 4.5.0
       pg:
         specifier: ^8.18.0
         version: 8.18.0
@@ -71,7 +80,7 @@ importers:
         version: 4.2.0(@japa/runner@4.5.0)
       '@japa/plugin-adonisjs':
         specifier: ^4.0.0
-        version: 4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)
+        version: 4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)
       '@japa/runner':
         specifier: ^4.2.0
         version: 4.5.0
@@ -804,6 +813,18 @@ packages:
   '@poppinss/validator-lite@2.1.2':
     resolution: {integrity: sha512-UhSG1ouT6r67VbEFHK/8ax3EMZYHioew9PqGmEZjV41G15aPZi6cyhXtBVvF9xqkHMflA5V680k7bQzV0kfD5w==}
 
+  '@scalar/core@0.3.42':
+    resolution: {integrity: sha512-RbyooMuG4oQEOhiA/tC+++bkIK1zeYGNxrTzSAgTrTzVlbFKPzw72fs4gX9/eHDo7qVc9FsymIW6qVpWbySzNg==}
+    engines: {node: '>=20'}
+
+  '@scalar/helpers@0.2.16':
+    resolution: {integrity: sha512-JlDUKdmwAHdcFUdTngNtx/uhLKTBACXlgvri7iKb6Jx6ImRIBgHwxZNAqlil1L047+QBrKh97lnezNpzNQAffQ==}
+    engines: {node: '>=20'}
+
+  '@scalar/types@0.6.7':
+    resolution: {integrity: sha512-ihHaoPF9qQR05pV3mfE7yBlHQdm5CoJVE0HiJFH6xSrzLfk2yJ6XdD3OzyRCqyxkZ38bj2RIZMS6LJsGy4p66g==}
+    engines: {node: '>=20'}
+
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
@@ -1045,6 +1066,9 @@ packages:
   '@speed-highlight/core@1.2.14':
     resolution: {integrity: sha512-G4ewlBNhUtlLvrJTb88d2mdy2KRijzs4UhnlrOSRT4bmjh/IqNElZa3zkrZ+TC47TwtlDWzVLFADljF1Ijp5hA==}
 
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
   '@stylistic/eslint-plugin@5.9.0':
     resolution: {integrity: sha512-FqqSkvDMYJReydrMhlugc71M76yLLQWNfmGq+SIlLa7N3kHp8Qq8i2PyWrVNAfjOyOIY+xv9XaaYwvVW7vroMA==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -1290,12 +1314,12 @@ packages:
     resolution: {integrity: sha512-KiROIzYdEV85YygXw6BI/Dx4fnBlFQu6Mq4QE4MOH9fFnhohw6wX/OAvDY2/C+ut0I3RSPKenvZJIVYqJNkhEw==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@vinejs/compiler@3.0.0':
-    resolution: {integrity: sha512-v9Lsv59nR56+bmy2p0+czjZxsLHwaibJ+SV5iK9JJfehlJMa501jUJQqqz4X/OqKXrxtE3uTQmSqjUqzF3B2mw==}
+  '@vinejs/compiler@4.1.3':
+    resolution: {integrity: sha512-UyH7Zn8dkTMLeU+PF2WjCnWkFb2qYaOxAcvp/uXW0njtKNcJOnVJaPsnWYwqewkTcHN47yvOdzosj3kj3RAP5w==}
     engines: {node: '>=18.0.0'}
 
-  '@vinejs/vine@3.0.1':
-    resolution: {integrity: sha512-ZtvYkYpZOYdvbws3uaOAvTFuvFXoQGAtmzeiXu+XSMGxi5GVsODpoI9Xu9TplEMuD/5fmAtBbKb9cQHkWkLXDQ==}
+  '@vinejs/vine@4.3.0':
+    resolution: {integrity: sha512-GaJY+PyTvcnjPvbL6pJhKNv4zl2vxFE5K8HoEf8LuTWrRa8WMB3jfS/MEywkbOLVQR1UlLxXNqAGcxgZfJcWkg==}
     engines: {node: '>=18.16.0'}
 
   abstract-logging@2.0.1:
@@ -1434,9 +1458,9 @@ packages:
     resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
     engines: {node: '>=6'}
 
-  camelcase@8.0.0:
-    resolution: {integrity: sha512-8WB3Jcas3swSvjIeA2yvCJ+Miyz5l1ZmB6HFb9R1317dt9LCQoswg/BGrmAmkWVEszSrrg4RwmO46qIm2OEnSA==}
-    engines: {node: '>=16'}
+  camelcase@9.0.0:
+    resolution: {integrity: sha512-TO9xmyXTZ9HUHI8M1OnvExxYB0eYVS/1e5s7IDMTAoIcwUd+aNcFODs6Xk83mobk0velyHFQgA1yIrvYc6wclw==}
+    engines: {node: '>=20'}
 
   caniuse-lite@1.0.30001770:
     resolution: {integrity: sha512-x/2CLQ1jHENRbHg5PSId2sXq1CIO1CISvwWAj027ltMVG2UNgW+w9oH2+HzgEIRFembL8bUlXtfbBHR1fCg2xw==}
@@ -2289,6 +2313,11 @@ packages:
     resolution: {integrity: sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==}
     hasBin: true
 
+  nanoid@5.1.6:
+    resolution: {integrity: sha512-c7+7RQ+dMB5dPwwCp4ee1/iV/q2P6aK1mTZcfr1BTuVlyW9hJYiMPybJCcnBlQtuSmTIWNeazm/zqNoZSSElBg==}
+    engines: {node: ^18 || >=20}
+    hasBin: true
+
   natural-compare@1.4.0:
     resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
 
@@ -2334,6 +2363,9 @@ packages:
     resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
     engines: {node: '>=18'}
 
+  openapi3-ts@4.5.0:
+    resolution: {integrity: sha512-jaL+HgTq2Gj5jRcfdutgRGLosCy/hT8sQf6VOy+P+g36cZOjI1iukdPnijC+4CmeRzg/jEllJUboEic2FhxhtQ==}
+
   optionator@0.9.4:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
@@ -2978,6 +3010,11 @@ packages:
     resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
     engines: {node: '>=0.4'}
 
+  yaml@2.8.2:
+    resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yargs-parser@21.1.1:
     resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
     engines: {node: '>=12'}
@@ -3006,6 +3043,9 @@ packages:
   youch@4.1.0-beta.14:
     resolution: {integrity: sha512-VqcHA/HqOxaBMjBQCYz1h8jYdAAeLm6cVLmefijJjMY4aovOfKkqMry7amNX3JiN4hXArb7ZVYBNpjEVkV3r/A==}
 
+  zod@4.3.6:
+    resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
+
 snapshots:
 
   '@adobe/css-tools@4.4.4': {}
@@ -3024,9 +3064,9 @@ snapshots:
       youch: 3.3.4
       youch-terminal: 2.2.3
 
-  '@adonisjs/ally@5.1.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))':
+  '@adonisjs/ally@5.1.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       '@poppinss/oauth-client': 7.0.2
       '@poppinss/utils': 6.10.1
 
@@ -3062,17 +3102,17 @@ snapshots:
     transitivePeerDependencies:
       - babel-plugin-macros
 
-  '@adonisjs/auth@9.6.0(9caa50a3b3df7d7047d71e59d2399cfb)':
+  '@adonisjs/auth@9.6.0(34f7b8323dd7e033f83e16958dfe5221)':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
-      '@adonisjs/presets': 2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
+      '@adonisjs/presets': 2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))
       '@poppinss/utils': 6.10.1
       basic-auth: 2.0.1
     optionalDependencies:
-      '@adonisjs/lucid': 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0)
-      '@adonisjs/session': 7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))
+      '@adonisjs/lucid': 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0)
+      '@adonisjs/session': 7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))
       '@japa/api-client': 3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0)
-      '@japa/plugin-adonisjs': 4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)
+      '@japa/plugin-adonisjs': 4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)
     transitivePeerDependencies:
       - '@adonisjs/assembler'
 
@@ -3093,17 +3133,17 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@adonisjs/bouncer@3.1.6(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))':
+  '@adonisjs/bouncer@3.1.6(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))':
     dependencies:
       '@poppinss/utils': 6.10.1
     optionalDependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
 
   '@adonisjs/config@5.0.3':
     dependencies:
       '@poppinss/utils': 6.10.1
 
-  '@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)':
+  '@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)':
     dependencies:
       '@adonisjs/ace': 13.4.0
       '@adonisjs/application': 8.4.2(@adonisjs/config@5.0.3)(@adonisjs/fold@10.2.1)
@@ -3135,17 +3175,17 @@ snapshots:
       youch-terminal: 2.2.3
     optionalDependencies:
       '@adonisjs/assembler': 7.8.2(typescript@5.8.3)
-      '@vinejs/vine': 3.0.1
+      '@vinejs/vine': 4.3.0
     transitivePeerDependencies:
       - supports-color
 
-  '@adonisjs/cors@2.2.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))':
+  '@adonisjs/cors@2.2.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
 
-  '@adonisjs/drive@3.4.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@aws-sdk/client-s3@3.995.0)(@aws-sdk/s3-request-presigner@3.995.0)':
+  '@adonisjs/drive@3.4.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@aws-sdk/client-s3@3.995.0)(@aws-sdk/s3-request-presigner@3.995.0)':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       flydrive: 1.3.0(@aws-sdk/client-s3@3.995.0)(@aws-sdk/s3-request-presigner@3.995.0)
     optionalDependencies:
       '@aws-sdk/client-s3': 3.995.0
@@ -3245,10 +3285,10 @@ snapshots:
       abstract-logging: 2.0.1
       pino: 10.3.1
 
-  '@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0)':
+  '@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0)':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
-      '@adonisjs/presets': 2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
+      '@adonisjs/presets': 2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))
       '@faker-js/faker': 9.9.0
       '@poppinss/hooks': 7.3.0
       '@poppinss/macroable': 1.1.0
@@ -3264,7 +3304,7 @@ snapshots:
       tarn: 3.0.2
     optionalDependencies:
       '@adonisjs/assembler': 7.8.2(typescript@5.8.3)
-      '@vinejs/vine': 3.0.1
+      '@vinejs/vine': 4.3.0
       luxon: 3.7.2
     transitivePeerDependencies:
       - better-sqlite3
@@ -3276,9 +3316,9 @@ snapshots:
       - supports-color
       - tedious
 
-  '@adonisjs/presets@2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))':
+  '@adonisjs/presets@2.6.4(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       '@poppinss/utils': 6.10.1
     optionalDependencies:
       '@adonisjs/assembler': 7.8.2(typescript@5.8.3)
@@ -3292,13 +3332,13 @@ snapshots:
       '@poppinss/colors': 4.1.6
       string-width: 7.2.0
 
-  '@adonisjs/session@7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))':
+  '@adonisjs/session@7.7.1(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@adonisjs/lucid@21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       '@poppinss/macroable': 1.1.0
       '@poppinss/utils': 6.10.1
     optionalDependencies:
-      '@adonisjs/lucid': 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@vinejs/vine@3.0.1)(luxon@3.7.2)(pg@8.18.0)
+      '@adonisjs/lucid': 21.8.2(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@vinejs/vine@4.3.0)(luxon@3.7.2)(pg@8.18.0)
       '@japa/api-client': 3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0)
 
   '@adonisjs/tsconfig@1.4.1': {}
@@ -3967,9 +4007,9 @@ snapshots:
       supports-color: 10.2.2
       youch: 4.1.0-beta.14
 
-  '@japa/plugin-adonisjs@4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)':
+  '@japa/plugin-adonisjs@4.0.0(@adonisjs/core@6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0))(@japa/api-client@3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0))(@japa/runner@4.5.0)':
     dependencies:
-      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@3.0.1)
+      '@adonisjs/core': 6.20.0(@adonisjs/assembler@7.8.2(typescript@5.8.3))(@vinejs/vine@4.3.0)
       '@japa/runner': 4.5.0
     optionalDependencies:
       '@japa/api-client': 3.2.1(@japa/assert@4.2.0(@japa/runner@4.5.0))(@japa/runner@4.5.0)
@@ -4131,6 +4171,19 @@ snapshots:
 
   '@poppinss/validator-lite@2.1.2': {}
 
+  '@scalar/core@0.3.42':
+    dependencies:
+      '@scalar/types': 0.6.7
+
+  '@scalar/helpers@0.2.16': {}
+
+  '@scalar/types@0.6.7':
+    dependencies:
+      '@scalar/helpers': 0.2.16
+      nanoid: 5.1.6
+      type-fest: 5.4.4
+      zod: 4.3.6
+
   '@sec-ant/readable-stream@0.4.1': {}
 
   '@sinclair/typebox@0.34.48': {}
@@ -4483,6 +4536,8 @@ snapshots:
 
   '@speed-highlight/core@1.2.14': {}
 
+  '@standard-schema/spec@1.1.0': {}
+
   '@stylistic/eslint-plugin@5.9.0(eslint@9.39.3)':
     dependencies:
       '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.3)
@@ -4749,14 +4804,16 @@ snapshots:
       '@typescript-eslint/types': 8.56.1
       eslint-visitor-keys: 5.0.1
 
-  '@vinejs/compiler@3.0.0': {}
+  '@vinejs/compiler@4.1.3': {}
 
-  '@vinejs/vine@3.0.1':
+  '@vinejs/vine@4.3.0':
     dependencies:
       '@poppinss/macroable': 1.1.0
+      '@poppinss/types': 1.2.1
+      '@standard-schema/spec': 1.1.0
       '@types/validator': 13.15.10
-      '@vinejs/compiler': 3.0.0
-      camelcase: 8.0.0
+      '@vinejs/compiler': 4.1.3
+      camelcase: 9.0.0
       dayjs: 1.11.19
       dlv: 1.1.3
       normalize-url: 8.1.1
@@ -4877,7 +4934,7 @@ snapshots:
 
   callsites@3.1.0: {}
 
-  camelcase@8.0.0: {}
+  camelcase@9.0.0: {}
 
   caniuse-lite@1.0.30001770: {}
 
@@ -5637,6 +5694,8 @@ snapshots:
 
   mustache@4.2.0: {}
 
+  nanoid@5.1.6: {}
+
   natural-compare@1.4.0: {}
 
   negotiator@0.6.3: {}
@@ -5678,6 +5737,10 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
+  openapi3-ts@4.5.0:
+    dependencies:
+      yaml: 2.8.2
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4
@@ -6283,6 +6346,8 @@ snapshots:
 
   xtend@4.0.2: {}
 
+  yaml@2.8.2: {}
+
   yargs-parser@21.1.1: {}
 
   yn@3.1.1: {}
@@ -6315,3 +6380,5 @@ snapshots:
       '@speed-highlight/core': 1.2.14
       cookie-es: 2.0.0
       youch-core: 0.3.3
+
+  zod@4.3.6: {}
diff --git a/start/routes.ts b/start/routes.ts
index bbdc6c0..159f82c 100644
--- a/start/routes.ts
+++ b/start/routes.ts
@@ -34,6 +34,8 @@ import router from '@adonisjs/core/services/router'
 import { middleware } from '#start/kernel'
 import app from '@adonisjs/core/services/app'
 import { UserGuard } from '#utils/permissions'
+import { getHtmlDocument } from '@scalar/core/libs/html-rendering'
+import { generateApiSpec } from '../docs/generator/index.js'
 
 router.get('/', async () => ({
   status: 200,
@@ -45,6 +47,22 @@ router.get('/status', async ({ auth }) => ({
   message: await auth.authenticate(),
 }))
 
+router.group(() => {
+  router.get('/openapi.json', async ({ response }) => {
+    if (app.inProduction)
+      response.download('docs/spec/openapi.json')
+    else
+      // eslint-disable-next-line @unicorn/no-await-expression-member
+      response.send((await generateApiSpec({ silent: true })).getSpecAsJson())
+  })
+  router.get('/', async ({ response }) => response.send(getHtmlDocument({
+    title: 'xContest API Documentation',
+    url: '/spec/openapi.json',
+    theme: 'purple',
+    darkMode: true,
+  })))
+}).prefix('/spec')
+
 // Temporary endpoint for development
 if (app.inDev)
   router.get('/adminme', async ({ auth }) => {
diff --git a/tsconfig.json b/tsconfig.json
index 86b69e8..70ada01 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -2,6 +2,6 @@
   "extends": "@adonisjs/tsconfig/tsconfig.app.json",
   "compilerOptions": {
     "rootDir": "./",
-    "outDir": "./build"
+    "outDir": "./build",
   }
 }

From e9c1f04dd5eb2302c5eb5aebff3c79c375b824f5 Mon Sep 17 00:00:00 2001
From: Oliwier Michalik <oliwier.michalik9@gmail.com>
Date: Thu, 26 Feb 2026 13:17:35 +0100
Subject: [PATCH 2/5] feat: implement some utilities for openapi generator

---
 app/controllers/auth_controller.ts |  2 +-
 docs/generator/decorators.ts       |  3 +-
 docs/generator/index.ts            | 52 +++++++++++++++++--
 docs/generator/tools.ts            | 80 ++++++++++++++++++++++++++++++
 docs/spec/openapi.json             |  2 +-
 package.json                       |  3 +-
 6 files changed, 134 insertions(+), 8 deletions(-)
 create mode 100644 docs/generator/tools.ts

diff --git a/app/controllers/auth_controller.ts b/app/controllers/auth_controller.ts
index fd8d3f0..e9f635c 100644
--- a/app/controllers/auth_controller.ts
+++ b/app/controllers/auth_controller.ts
@@ -29,7 +29,7 @@ import {
   ApiOperation,
   ApiRequest,
   ApiResponse,
-} from '../../docs/generator/decorators.js'
+} from '#openapi/decorators'
 
 export default class AuthController {
   @ApiOperation({ description: 'Redirects to the social provider for authentication' })
diff --git a/docs/generator/decorators.ts b/docs/generator/decorators.ts
index fadfd68..4a4486e 100644
--- a/docs/generator/decorators.ts
+++ b/docs/generator/decorators.ts
@@ -25,6 +25,7 @@ import 'reflect-metadata'
 import type { VineValidator } from '@vinejs/vine'
 import type { BaseModel } from '@adonisjs/lucid/orm'
 import type { SchemaObjectFormat } from 'openapi3-ts/oas30'
+import type { _Merged } from './tools.js'
 
 const makeMetaDecorator = <Args extends any[]>(tag: string, transformArgs: (args: Args) => any = (a) => a[0], acceptClass: boolean = false) =>
   (...args: Args) => (target: any, propertyKey?: string | symbol) => {
@@ -52,7 +53,7 @@ export type ApiRequestOptions = {
 } // TODO: Add support for custom request data if necessary in the future
 export const ApiRequest = makeMetaDecorator<[ApiRequestOptions]>('spec:requestBody')
 
-export type PrimitiveResponseDataType = typeof BaseModel | object
+export type PrimitiveResponseDataType = typeof BaseModel | typeof _Merged | object
 export type ResponseDataType = PrimitiveResponseDataType | [PrimitiveResponseDataType]
 
 export type ApiResponseOptions = {
diff --git a/docs/generator/index.ts b/docs/generator/index.ts
index f006404..6fb33a7 100644
--- a/docs/generator/index.ts
+++ b/docs/generator/index.ts
@@ -21,8 +21,6 @@
  *
  */
 
-/* eslint-disable no-console */
-
 import app from '@adonisjs/core/services/app'
 import type { HttpRouterService } from '@adonisjs/core/types'
 import type { OperationObject, PathItemObject, ResponsesObject, SchemaObject, TagObject } from 'openapi3-ts/oas31'
@@ -51,8 +49,13 @@ type PartialOperation = Promise<Partial<OperationObject>>
 let IS_SILENT = false
 const log = (...args: any[]) => {
   if (!IS_SILENT)
+    // eslint-disable-next-line no-console
     console.log(...args)
 }
+const warn = (message: string) => {
+  // eslint-disable-next-line no-console
+  console.log(colors.yellow(`  ! ${message}`))
+}
 
 // Gets api tag for a route handler.
 // It first checks for a tag on controller method, then controller class,
@@ -180,10 +183,14 @@ const generateSchemaForDataType = (schemas: { [key: string]: SchemaObject }, dat
 
         if (!columnData?.type) {
           // @ts-ignore
-          log(colors.yellow(`  ! Couldn't infer type for column ${column} on model for table ${data.table}. Please add @ApiColumn decorator to the column in question.`))
+          warn(`Couldn't infer type for column ${column} on model for table ${data.table}. Please add @ApiColumn decorator to the column in question.`)
           return null
         }
 
+        if ('type' in columnData?.type)
+          // @ts-ignore
+          warn(`Found field 'type' on column type. @ApiColumn takes two *separate* arguments: type and options. ${column}@${data.table}`)
+
         const baseType: Partial<SchemaObject>
           = generateSchemaForDataType(schemas, columnData.type) ?? {
             type: 'null',
@@ -206,6 +213,12 @@ const generateSchemaForDataType = (schemas: { [key: string]: SchemaObject }, dat
       required: requiredFields,
     }
     return { $ref: `#/components/schemas/${modelName}` }
+  } else if (data instanceof _ApiWrappedData) {
+    const values = data.values.map((value) => generateSchemaForDataType(schemas, value))
+
+    if (values.some((value) => value === undefined || value === null))
+      throw new Error('Invalid wrapped data. All values must be defined and non-null.')
+    return data.wrapper(values as SchemaObject[])
   } else if ('toJSONSchema' in data && typeof data.toJSONSchema === 'function')
     return data.toJSONSchema() as SchemaObject
   else if (data === Number)
@@ -220,7 +233,27 @@ const generateSchemaForDataType = (schemas: { [key: string]: SchemaObject }, dat
     return { type: 'string', format: 'date' }
   else if (data === DateTime)
     return { type: 'string', format: 'date-time' }
-  else
+  // @ts-ignore
+  else if (!data.prototype) { // Some primitive object
+    const requiredFields: string[] = []
+    return {
+      type: 'object',
+      properties: Object.fromEntries(
+        Object.entries(data).map(([key, value]) => {
+          if (!key.startsWith('_')) // _name is optional
+            requiredFields.push(key)
+          return [
+            key.replace(/^_/g, ''),
+            generateSchemaForDataType(schemas, value) ?? {
+              type: 'null',
+              description: 'Failed to infer',
+            },
+          ]
+        }),
+      ),
+      required: requiredFields,
+    }
+  } else
     throw new Error(`Unsupported data type for response body: ${typeof data}`)
 }
 
@@ -326,3 +359,14 @@ export const generateApiSpec = async (config?: { silent?: boolean }) => {
   Object.entries(operations).forEach(([path, operation]) => builder.addPath(path, operation))
   return builder
 }
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export class _ApiWrappedData {
+  public values: ResponseDataType[]
+  public wrapper: (values: SchemaObject[]) => SchemaObject
+
+  constructor(values: ResponseDataType[], wrapper: (values: SchemaObject[]) => SchemaObject) {
+    this.values = values
+    this.wrapper = wrapper
+  }
+}
diff --git a/docs/generator/tools.ts b/docs/generator/tools.ts
new file mode 100644
index 0000000..5d51a9b
--- /dev/null
+++ b/docs/generator/tools.ts
@@ -0,0 +1,80 @@
+/*
+ *          ______            __            __
+ *    _  __/ ____/___  ____  / /____  _____/ /_
+ *   | |/_/ /   / __ \/ __ \/ __/ _ \/ ___/ __/
+ *  _>  </ /___/ /_/ / / / / /_/  __(__  ) /_
+ * /_/|_|\____/\____/_/ /_/\__/\___/____/\__/
+ *     Copyright (C) 2026 xContest Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/.
+ *
+ */
+
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+import { ApiColumn, ResponseDataType } from './decorators.js'
+import { _ApiWrappedData } from './index.js'
+
+export const paginated = (data: ResponseDataType) => ({
+  meta: PaginationMeta,
+  data,
+})
+
+export const merged = (...objects: ResponseDataType[]): ResponseDataType =>
+  new _ApiWrappedData(objects, (values) => ({ allOf: values }))
+
+export const alternative = (...objects: ResponseDataType[]): ResponseDataType =>
+  new _ApiWrappedData(objects, (values) => ({ oneOf: values }))
+
+// A bit of a hacky solution to ensure metadata is represented as
+// a single model and not inserted every time as a schema
+// THIS TABLE SHOULD NOT BE IN A DATABASE!!! IT IS FOR OPENAPI SPEC ONLY
+class PaginationMeta extends BaseModel {
+  static table = 'pagination_meta_not_put_in_a_database'
+
+  @column()
+  @ApiColumn(Number)
+  declare total: null
+
+  @column()
+  @ApiColumn(Number, { example: 25 })
+  declare perPage: null
+
+  @column()
+  @ApiColumn(Number)
+  declare currentPage: null
+
+  @column()
+  @ApiColumn(Number, { example: 3 })
+  declare lastPage: null
+
+  @column()
+  @ApiColumn(Number)
+  declare firstPage: null
+
+  @column()
+  @ApiColumn(String, { example: '/data?page=1' })
+  declare firstPageUrl: null
+
+  @column()
+  @ApiColumn(String, { example: '/data?page=3' })
+  declare lastPageUrl: null
+
+  @column()
+  @ApiColumn(String, { required: false, example: '/data?page=2' })
+  declare nextPageUrl: null
+
+  @column()
+  @ApiColumn(String, { required: false, example: null })
+  declare previousPageUrl: null
+}
diff --git a/docs/spec/openapi.json b/docs/spec/openapi.json
index 78ccf22..09a2c37 100644
--- a/docs/spec/openapi.json
+++ b/docs/spec/openapi.json
@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}}}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"]},"post":{"operationId":"EventsController.store","tags":["Events"]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"]},"put":{"operationId":"EventsController.update","tags":["Events"]},"patch":{"operationId":"EventsController.update","tags":["Events"]},"delete":{"operationId":"EventsController.destroy","tags":["Events"]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"]},"patch":{"operationId":"TeamsController.update","tags":["Teams"]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"]},"patch":{"operationId":"TasksController.update","tags":["Tasks"]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
+{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}},"security":[{"session":[]}]}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"]},"post":{"operationId":"EventsController.store","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"]},"put":{"operationId":"EventsController.update","tags":["Events"],"security":[{"session":[]}]},"patch":{"operationId":"EventsController.update","tags":["Events"],"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroy","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"],"security":[{"session":[]}]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"security":[{"session":[]}]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"],"security":[{"session":[]}]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"patch":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"],"security":[{"session":[]}]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"],"security":[{"session":[]}]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"],"security":[{"session":[]}]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"],"security":[{"session":[]}]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"],"security":[{"session":[]}]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"],"security":[{"session":[]}]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"patch":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"],"security":[{"session":[]}]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"],"security":[{"session":[]}]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"],"security":[{"session":[]}]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"],"security":[{"session":[]}]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"xcontest-session"}},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
diff --git a/package.json b/package.json
index 6dbd8c6..4ba11ee 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,8 @@
     "#database/*": "./database/*.js",
     "#start/*": "./start/*.js",
     "#tests/*": "./tests/*.js",
-    "#config/*": "./config/*.js"
+    "#config/*": "./config/*.js",
+    "#openapi/*": "./docs/generator/*.js"
   },
   "devDependencies": {
     "@adonisjs/assembler": "^7.8.2",

From c460321e649c3631b25ddaced477d12a68163dec Mon Sep 17 00:00:00 2001
From: Oliwier Michalik <oliwier.michalik9@gmail.com>
Date: Thu, 26 Feb 2026 13:39:27 +0100
Subject: [PATCH 3/5] feat: implement apidoc for events and event
 administrators

---
 app/controllers/events_controller.ts    | 73 +++++++++++++++----------
 app/models/event/event.ts               | 12 +++-
 app/models/event/event_administrator.ts |  7 +++
 docs/generator/decorators.ts            |  4 +-
 docs/spec/openapi.json                  |  2 +-
 5 files changed, 64 insertions(+), 34 deletions(-)

diff --git a/app/controllers/events_controller.ts b/app/controllers/events_controller.ts
index a28a9ed..7404127 100644
--- a/app/controllers/events_controller.ts
+++ b/app/controllers/events_controller.ts
@@ -30,26 +30,27 @@ import { EventAdminGuard } from '#utils/permissions'
 import type { Mask , EventAdminPermissions } from '#utils/permissions'
 import EventPolicy from '#policies/event_policy'
 import { confirmationValidator } from '#validators/common'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
 
 export default class EventsController {
-  /**
-   * Display a list of resource
-   */
+  @ApiOperation({ description: 'Get a list of all active events' })
+  @ApiResponse(200, { description: 'A list of active events', data: [Event] })
   async index({}: HttpContext) {
     return Event.query().where('status', 'ACTIVE')
   }
 
-  /**
-   * Handle form submission for the creation action
-   */
+  @ApiOperation({ description: 'Create a new event' })
+  @ApiRequest({ validator: createEventValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created event', data: Event })
+  @ApiResponse(403, { description: 'Missing permission to create events' })
   async store({ auth, bouncer, request, response }: HttpContext) {
     await bouncer.with(EventPolicy).authorize('create')
 
     const payload = await request.validateUsing(createEventValidator)
 
-    if (payload.minTeamSize > payload.maxTeamSize) 
-      return response.unprocessableEntity({ message: 'minTeamSize cannot be greater than maxTeamSize.' })
-    
+    if (payload.minTeamSize > payload.maxTeamSize)
+      return response.unprocessableEntity({ errors: [{ message: 'minTeamSize cannot be greater than maxTeamSize.' }] })
+
 
     const event = await db.transaction(async (trx) => {
       const newEvent = await Event.create(payload, { client: trx })
@@ -65,9 +66,10 @@ export default class EventsController {
     return response.created(event)
   }
 
-  /**
-   * Show individual record
-   */
+  @ApiOperation({ description: 'Get a specific event by its slug or UUID' })
+  @ApiResponse(200, { description: 'The requested event', data: Event })
+  @ApiResponse(404, { description: 'Event not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async show({ bouncer, params }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
 
@@ -76,9 +78,11 @@ export default class EventsController {
     return event
   }
 
-  /**
-   * Handle form submission for the edit action
-   */
+  @ApiOperation({ description: 'Update an existing event by its slug or UUID' })
+  @ApiRequest({ validator: updateEventValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated event', data: Event })
+  @ApiResponse(404, { description: 'Event not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this event' })
   async update({ bouncer, params, request }: HttpContext) {
     const payload = await request.validateUsing(updateEventValidator, {
       meta: { eventSlug: params.id },
@@ -93,9 +97,11 @@ export default class EventsController {
     return event
   }
 
-  /**
-   * Delete record
-   */
+  @ApiOperation({ description: 'Delete an event by its slug or UUID. Requires confirmation of the event slug.' })
+  @ApiRequest({ validator: confirmationValidator, withResponse: true })
+  @ApiResponse(204, { description: 'Event deleted successfully' })
+  @ApiResponse(404, { description: 'Event not found' })
+  @ApiResponse(403, { description: 'Missing permission to delete this event' })
   async destroy({ bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
     await request.validateUsing(confirmationValidator, {
@@ -111,9 +117,10 @@ export default class EventsController {
     return response.noContent()
   }
 
-  /**
-   * List all administrators for an event
-   */
+  @ApiOperation({ description: 'Get a list of all administrators for an event' })
+  @ApiResponse(200, { description: 'A list of administrators for the event', data: [EventAdministrator] })
+  @ApiResponse(404, { description: 'Event not found' })
+  @ApiResponse(403, { description: 'Missing permission to view administrators for this event' })
   async indexAdministrators({ bouncer, params }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
     await bouncer.with(EventPolicy).authorize('manageAdministrators', event)
@@ -121,9 +128,12 @@ export default class EventsController {
     return event.related('administrators').query().preload('user')
   }
 
-  /**
-   * Assign a user as an administrator for an event
-   */
+  @ApiOperation({ description: 'Create a new administrator for an event' })
+  @ApiRequest({ validator: storeAdministratorValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created administrator', data: EventAdministrator })
+  @ApiResponse(404, { description: 'Event not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage administrators for this event' })
+  @ApiResponse(409, { description: 'User is already an administrator of this event' })
   async storeAdministrator({ bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
     await bouncer.with(EventPolicy).authorize('manageAdministrators', event)
@@ -146,9 +156,11 @@ export default class EventsController {
     return response.created(admin)
   }
 
-  /**
-   * Update permissions (bitmask) of an event administrator
-   */
+  @ApiOperation({ description: 'Update permissions for an event administrator' })
+  @ApiRequest({ validator: updateAdministratorValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated administrator', data: EventAdministrator })
+  @ApiResponse(404, { description: 'Event or administrator not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage administrators for this event' })
   async updateAdministrator({ bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
     await bouncer.with(EventPolicy).authorize('manageAdministrators', event)
@@ -169,9 +181,10 @@ export default class EventsController {
     return admin
   }
 
-  /**
-   * Revoke administrator access from a user for an event
-   */
+  @ApiOperation({ description: 'Remove administrator from an event' })
+  @ApiResponse(204, { description: 'Administrator removed successfully' })
+  @ApiResponse(404, { description: 'Event or administrator not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage administrators for this event' })
   async destroyAdministrator({ bouncer, params, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.id)
     await bouncer.with(EventPolicy).authorize('manageAdministrators', event)
diff --git a/app/models/event/event.ts b/app/models/event/event.ts
index 4833648..652eda1 100644
--- a/app/models/event/event.ts
+++ b/app/models/event/event.ts
@@ -31,36 +31,47 @@ import Team from '#models/team/team'
 import Task from '#models/task/task'
 import Organization from '#models/organization'
 import { uuidV4Regex } from '#validators/common'
+import { ApiColumn } from '#openapi/decorators'
+import vine from '@vinejs/vine'
 
 export default class Event extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'best-hackathon-ever' })
   declare slug: string
 
   @column()
+  @ApiColumn(String, { example: 'Awesome Hackathon' })
   declare title: string
 
   @column()
+  @ApiColumn(String, { example: 'A first ever hackathon using a modern platform' })
   declare description: string
 
   @column({ serializeAs: null })
   declare accessCode: string | null
 
   @column()
+  @ApiColumn(vine.enum(['DRAFT', 'ACTIVE', 'ARCHIVED']), { example: 'ACTIVE' })
   declare status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED'
 
   @column()
+  @ApiColumn(Number)
   declare minTeamSize: number
 
   @column()
+  @ApiColumn(Number, { example: 4 })
   declare maxTeamSize: number
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @hasMany(() => EventAdministrator)
@@ -93,7 +104,6 @@ export default class Event extends BaseModel {
     if (!event)
       throw new Exception('Event not found', { status: 404, code: 'E_EVENT_NOT_FOUND' })
 
-
     return event
   }
 }
diff --git a/app/models/event/event_administrator.ts b/app/models/event/event_administrator.ts
index c868a7e..2166dec 100644
--- a/app/models/event/event_administrator.ts
+++ b/app/models/event/event_administrator.ts
@@ -28,24 +28,31 @@ import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import Event from '#models/event/event'
 import User from '#models/user'
 import type { EventAdminPermissions, Mask } from '#utils/permissions'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class EventAdministrator extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08a' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare eventId: string
 
   @column()
+  @ApiColumn(Number)
   declare userId: number
 
   @column()
+  @ApiColumn(Number, { format: 'binary' })
   declare permissions: Mask<typeof EventAdminPermissions>
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Event)
diff --git a/docs/generator/decorators.ts b/docs/generator/decorators.ts
index 4a4486e..b49c717 100644
--- a/docs/generator/decorators.ts
+++ b/docs/generator/decorators.ts
@@ -25,7 +25,7 @@ import 'reflect-metadata'
 import type { VineValidator } from '@vinejs/vine'
 import type { BaseModel } from '@adonisjs/lucid/orm'
 import type { SchemaObjectFormat } from 'openapi3-ts/oas30'
-import type { _Merged } from './tools.js'
+import type { _ApiWrappedData } from '#openapi/index'
 
 const makeMetaDecorator = <Args extends any[]>(tag: string, transformArgs: (args: Args) => any = (a) => a[0], acceptClass: boolean = false) =>
   (...args: Args) => (target: any, propertyKey?: string | symbol) => {
@@ -53,7 +53,7 @@ export type ApiRequestOptions = {
 } // TODO: Add support for custom request data if necessary in the future
 export const ApiRequest = makeMetaDecorator<[ApiRequestOptions]>('spec:requestBody')
 
-export type PrimitiveResponseDataType = typeof BaseModel | typeof _Merged | object
+export type PrimitiveResponseDataType = typeof BaseModel | typeof _ApiWrappedData | object
 export type ResponseDataType = PrimitiveResponseDataType | [PrimitiveResponseDataType]
 
 export type ApiResponseOptions = {
diff --git a/docs/spec/openapi.json b/docs/spec/openapi.json
index 09a2c37..7d6aec7 100644
--- a/docs/spec/openapi.json
+++ b/docs/spec/openapi.json
@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}},"security":[{"session":[]}]}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"]},"post":{"operationId":"EventsController.store","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"]},"put":{"operationId":"EventsController.update","tags":["Events"],"security":[{"session":[]}]},"patch":{"operationId":"EventsController.update","tags":["Events"],"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroy","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"],"security":[{"session":[]}]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"],"security":[{"session":[]}]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"security":[{"session":[]}]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"],"security":[{"session":[]}]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"patch":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"],"security":[{"session":[]}]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"],"security":[{"session":[]}]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"],"security":[{"session":[]}]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"],"security":[{"session":[]}]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"],"security":[{"session":[]}]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"],"security":[{"session":[]}]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"patch":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"],"security":[{"session":[]}]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"],"security":[{"session":[]}]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"],"security":[{"session":[]}]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"],"security":[{"session":[]}]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"xcontest-session"}},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
+{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}},"security":[{"session":[]}]}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"],"description":"Get a list of all active events","responses":{"200":{"description":"A list of active events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"post":{"operationId":"EventsController.store","tags":["Events"],"description":"Create a new event","responses":{"201":{"description":"The newly created event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to create events"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"}},"required":["title","description","status","minTeamSize","maxTeamSize","slug"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"],"description":"Get a specific event by its slug or UUID","responses":{"200":{"description":"The requested event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Event not found"}}},"put":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroy","tags":["Events"],"description":"Delete an event by its slug or UUID. Requires confirmation of the event slug.","responses":{"204":{"description":"Event deleted successfully"},"403":{"description":"Missing permission to delete this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmation":{"type":"string"}},"required":["confirmation"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"],"description":"Get a list of all administrators for an event","responses":{"200":{"description":"A list of administrators for the event","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventAdministrator"}}}}},"403":{"description":"Missing permission to view administrators for this event"},"404":{"description":"Event not found"}},"security":[{"session":[]}]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"],"description":"Create a new administrator for an event","responses":{"201":{"description":"The newly created administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event not found"},"409":{"description":"User is already an administrator of this event"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"number","minimum":0},"permissions":{"type":"number","minimum":0}},"required":["userId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"],"description":"Remove administrator from an event","responses":{"204":{"description":"Administrator removed successfully"},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"}},"security":[{"session":[]}]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"patch":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"],"security":[{"session":[]}]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"],"security":[{"session":[]}]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"],"security":[{"session":[]}]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"],"security":[{"session":[]}]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"],"security":[{"session":[]}]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"],"security":[{"session":[]}]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"patch":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"],"security":[{"session":[]}]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"],"security":[{"session":[]}]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"],"security":[{"session":[]}]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"],"security":[{"session":[]}]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]},"Event":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"slug":{"example":"best-hackathon-ever","type":"string"},"title":{"example":"Awesome Hackathon","type":"string"},"description":{"example":"A first ever hackathon using a modern platform","type":"string"},"status":{"example":"ACTIVE","enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number"},"maxTeamSize":{"example":4,"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","title","description","status","minTeamSize","maxTeamSize","createdAt","updatedAt"]},"EventAdministrator":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08a","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"userId":{"type":"number"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","eventId","userId","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"xcontest-session"}},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file

From 657d135b38e3e0d39ba3fc9a6469c008254ff907 Mon Sep 17 00:00:00 2001
From: Oliwier Michalik <oliwier.michalik9@gmail.com>
Date: Thu, 26 Feb 2026 15:16:29 +0100
Subject: [PATCH 4/5] feat: implement config for openapi generation

---
 commands/generate_spec.ts    |   7 +--
 config/openapi.ts            |  46 +++++++++++++++
 docs/generator/decorators.ts |  14 ++++-
 docs/generator/index.ts      | 108 +++++++++++++++++++++++++----------
 docs/generator/tools.ts      |   2 +-
 docs/spec/openapi.json       |   1 -
 start/routes.ts              |  10 +---
 7 files changed, 142 insertions(+), 46 deletions(-)
 create mode 100644 config/openapi.ts
 delete mode 100644 docs/spec/openapi.json

diff --git a/commands/generate_spec.ts b/commands/generate_spec.ts
index 5dc67c9..24460d2 100644
--- a/commands/generate_spec.ts
+++ b/commands/generate_spec.ts
@@ -24,9 +24,7 @@
 import { BaseCommand } from '@adonisjs/core/ace'
 import type { CommandOptions } from '@adonisjs/core/types/ace'
 import app from '@adonisjs/core/services/app'
-import { generateApiSpec } from '../docs/generator/index.js'
-import * as fs from 'node:fs'
-import path from 'node:path'
+import { generateApiSpec } from '#openapi/index'
 
 export default class GenerateSpec extends BaseCommand {
   static commandName = 'generate:spec'
@@ -39,7 +37,6 @@ export default class GenerateSpec extends BaseCommand {
     await app.start(() => {})
     await app.ready(() => {})
 
-    const spec = await generateApiSpec()
-    fs.writeFileSync(path.join(import.meta.dirname, '../docs/spec/openapi.json'), spec.getSpecAsJson())
+    await generateApiSpec({ makeServer: true })
   }
 }
diff --git a/config/openapi.ts b/config/openapi.ts
new file mode 100644
index 0000000..89c8b4b
--- /dev/null
+++ b/config/openapi.ts
@@ -0,0 +1,46 @@
+/*
+ *          ______            __            __
+ *    _  __/ ____/___  ____  / /____  _____/ /_
+ *   | |/_/ /   / __ \/ __ \/ __/ _ \/ ___/ __/
+ *  _>  </ /___/ /_/ / / / / /_/  __(__  ) /_
+ * /_/|_|\____/\____/_/ /_/\__/\___/____/\__/
+ *     Copyright (C) 2026 xContest Team
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/.
+ *
+ */
+
+import type { ApiSpecGeneratorConfig } from '#openapi/index'
+import path from 'node:path'
+
+const openapiConfig: ApiSpecGeneratorConfig = {
+  hideDefaultTag: true,
+  info: {
+    title: 'xContest REST API',
+    description: 'Specification document for REST API component of xContest platform',
+    version: '1.0.0', // TODO: Get this from package?
+  },
+  output: {
+    directory: path.join(import.meta.dirname, '../docs/spec'),
+    emitHtml: true,
+    htmlConfig: {
+      url: '/spec/openapi.json',
+      title: 'xContest REST API',
+      theme: 'purple',
+      darkMode: true,
+    },
+  },
+}
+
+export default openapiConfig
diff --git a/docs/generator/decorators.ts b/docs/generator/decorators.ts
index b49c717..12969e3 100644
--- a/docs/generator/decorators.ts
+++ b/docs/generator/decorators.ts
@@ -51,7 +51,19 @@ export type ApiRequestOptions = {
   validator: VineValidator<any, any>,
   withResponse?: boolean
 } // TODO: Add support for custom request data if necessary in the future
-export const ApiRequest = makeMetaDecorator<[ApiRequestOptions]>('spec:requestBody')
+export const ApiRequest = (options: ApiRequestOptions) =>
+  (target: any, propertyKey: string | symbol) => {
+    if (!propertyKey)
+      throw new Error('Decorator ApiRequest can only be applied to methods')
+
+    const current = Reflect.getMetadata('spec:requestBody', target, propertyKey) ?? []
+    Reflect.defineMetadata(
+      'spec:requestBody',
+      [...current, options],
+      target,
+      propertyKey,
+    )
+  }
 
 export type PrimitiveResponseDataType = typeof BaseModel | typeof _ApiWrappedData | object
 export type ResponseDataType = PrimitiveResponseDataType | [PrimitiveResponseDataType]
diff --git a/docs/generator/index.ts b/docs/generator/index.ts
index 6fb33a7..fa30267 100644
--- a/docs/generator/index.ts
+++ b/docs/generator/index.ts
@@ -23,7 +23,7 @@
 
 import app from '@adonisjs/core/services/app'
 import type { HttpRouterService } from '@adonisjs/core/types'
-import type { OperationObject, PathItemObject, ResponsesObject, SchemaObject, TagObject } from 'openapi3-ts/oas31'
+import type { InfoObject, OperationObject, PathItemObject, ResponsesObject, SchemaObject, TagObject } from 'openapi3-ts/oas31'
 import { OpenApiBuilder } from 'openapi3-ts/oas31'
 import useColors from '@poppinss/colors'
 import type {
@@ -33,11 +33,14 @@ import type {
   ApiResponseData,
   ResponseDataType,
 } from './decorators.js'
-import type { VineAny } from '@vinejs/vine'
+import type { VineAny, VineValidator } from '@vinejs/vine'
 import vine from '@vinejs/vine'
 import { BaseModel } from '@adonisjs/lucid/orm'
 import type { ColumnOptions } from '@adonisjs/lucid/types/model'
 import { DateTime } from 'luxon'
+import openapiConfig from '#config/openapi'
+import { getHtmlDocument, type HtmlRenderingConfiguration } from '@scalar/core/libs/html-rendering'
+import * as fs from 'node:fs/promises'
 
 const colors = useColors.ansi()
 
@@ -96,7 +99,7 @@ const getOperationIdFor = (handler: RouteHandler, pattern: string): string => {
 
 // Replaces an Adonis pattern with the OpenAPI path. (e.g. '/users/:id' -> '/users/{id}')
 const convertPatternToPath = (pattern: string) =>
-  pattern.replace(/:([a-zA-Z]+)/g, '{$1}')
+  pattern.replace(/:([a-zA-Z_]+)/g, '{$1}')
 
 // Generate basic data for an operation.
 // This includes summary, description, and deprecated status.
@@ -108,42 +111,55 @@ const generateOperationData = async (route: Route): PartialOperation => {
 // Generate request data for an operation.
 // This includes parameters and request body schema.
 const generateRequestData = async (route: Route): Promise<PartialOperation> => {
-  const requestBody = await getMetaTag<ApiRequestOptions>(route.handler, 'spec:requestBody')
-  if (!requestBody)
+  const requestBodies = await getMetaTag<ApiRequestOptions[]>(route.handler, 'spec:requestBody')
+  if (!requestBodies)
     return {}
 
   const data: Partial<OperationObject> = {
     parameters: [], // This function is called before parameters are generated.
   }
 
-  if ('validator' in requestBody) {
-    const validator = requestBody.validator
-    const properties = validator.schema.getProperties()
-
-    // Take params from the validator
-    const { params, ...rest } = properties
-    const paramsObj = params ? params.getProperties() : {}
+  for (const requestBody of requestBodies)
+    if ('validator' in requestBody) {
+      const validator = requestBody.validator as VineValidator<any, any>
+      const properties = validator.schema.getProperties()
+
+      // Take params from the validator
+      const { params, qs, ...rest } = properties
+      const paramsObj = params ? params.getProperties() : {}
+      const qsObj = qs ? qs.getProperties() : {}
+
+      // Path properties
+      for (const [key, value] of Object.entries(paramsObj as Record<string, VineAny>))
+        data.parameters!.push({
+          name: key,
+          in: 'path',
+          required: true,
+          schema: value.toJSONSchema() as SchemaObject,
+        })
 
-    for (const [key, value] of Object.entries(paramsObj as Record<string, VineAny>))
-      data.parameters!.push({
-        name: key,
-        in: 'path',
-        required: true,
-        schema: value.toJSONSchema() as SchemaObject,
-      })
+      // Query string
+      for (const [key, value] of Object.entries(qsObj as Record<string, VineAny>))
+        data.parameters!.push({
+          name: key,
+          in: 'query',
+          required: false,
+          schema: value.toJSONSchema() as SchemaObject,
+        })
 
-    if (rest && Object.keys(rest).length > 0) {
-      const restObj = vine.object(rest)
+      // Body
+      if (rest && Object.keys(rest).length > 0) {
+        const restObj = vine.object(rest)
 
-      data.requestBody = {
-        content: {
-          'application/json': {
-            schema: restObj.toJSONSchema() as SchemaObject,
+        data.requestBody = {
+          content: {
+            'application/json': {
+              schema: restObj.toJSONSchema() as SchemaObject,
+            },
           },
-        },
+        }
       }
     }
-  }
 
   return data
 }
@@ -306,12 +322,24 @@ const generateResponseData = async (schemas: { [key: string]: SchemaObject }, ro
   return { responses }
 }
 
+export type ApiSpecGeneratorConfig = {
+  hideDefaultTag?: boolean,
+  info: InfoObject,
+  output: {
+    directory: string,
+    emitHtml: boolean,
+    htmlConfig?: Partial<HtmlRenderingConfiguration>
+  }
+}
+
 // Automatically generate OpenApi3 spec from decorators on Adonis controllers.
-export const generateApiSpec = async (config?: { silent?: boolean }) => {
+export const generateApiSpec = async (config?: { silent?: boolean, makeServer?: boolean }) => {
   IS_SILENT = config?.silent ?? false
   log(colors.yellow('Generating OpenAPI spec...'))
-  const server = await app.container.make('server')
-  await server.boot()
+  if (config?.makeServer) {
+    const server = await app.container.make('server')
+    await server.boot()
+  }
   const router = await app.container.make('router')
 
   const tags: Record<string, TagObject> = {}
@@ -321,6 +349,9 @@ export const generateApiSpec = async (config?: { silent?: boolean }) => {
   for (const route of router.toJSON().root) {
     log(colors.gray(`❯ Processing route ${route.pattern}`))
     const apiTag = await getApiTagFor(route.handler)
+    if (openapiConfig.hideDefaultTag && apiTag.name === 'Default')
+      continue
+
     tags[apiTag.name] = apiTag
 
     const path = convertPatternToPath(route.pattern)
@@ -357,6 +388,23 @@ export const generateApiSpec = async (config?: { silent?: boolean }) => {
   Object.values(tags).forEach((tag) => builder.addTag(tag))
   Object.entries(schemas).forEach(([name, schema]) => builder.addSchema(name, schema))
   Object.entries(operations).forEach(([path, operation]) => builder.addPath(path, operation))
+
+  builder.addInfo(openapiConfig.info)
+
+  log(colors.gray(`❯ Emitting output to ${openapiConfig.output.directory}`))
+  await fs.writeFile(`${openapiConfig.output.directory}/openapi.json`, builder.getSpecAsJson(), 'utf-8')
+  log(colors.green('  ✔') + colors.gray(' openapi.json generated.'))
+  if (openapiConfig.output.emitHtml) {
+    await fs.writeFile(
+      `${openapiConfig.output.directory}/spec.html`,
+      // @ts-ignore
+      getHtmlDocument(openapiConfig.output.htmlConfig),
+      'utf-8',
+    )
+    log(colors.green('  ✔') + colors.gray(' spec.html generated.'))
+  }
+
+  log(colors.green('OpenAPI spec generation complete!'))
   return builder
 }
 
diff --git a/docs/generator/tools.ts b/docs/generator/tools.ts
index 5d51a9b..6fe5595 100644
--- a/docs/generator/tools.ts
+++ b/docs/generator/tools.ts
@@ -27,7 +27,7 @@ import { _ApiWrappedData } from './index.js'
 
 export const paginated = (data: ResponseDataType) => ({
   meta: PaginationMeta,
-  data,
+  data: [data],
 })
 
 export const merged = (...objects: ResponseDataType[]): ResponseDataType =>
diff --git a/docs/spec/openapi.json b/docs/spec/openapi.json
deleted file mode 100644
index 7d6aec7..0000000
--- a/docs/spec/openapi.json
+++ /dev/null
@@ -1 +0,0 @@
-{"openapi":"3.1.0","info":{"title":"app","version":"version"},"paths":{"/":{"get":{"operationId":"global.index","tags":["Default"]}},"/status":{"get":{"operationId":"global.status","tags":["Default"]}},"/spec/openapi.json":{"get":{"operationId":"global.spec/openapi.json","tags":["Default"]}},"/spec":{"get":{"operationId":"global.spec","tags":["Default"]}},"/adminme":{"get":{"operationId":"global.adminme","tags":["Default"]}},"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}},"security":[{"session":[]}]}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"],"description":"Get a list of all active events","responses":{"200":{"description":"A list of active events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"post":{"operationId":"EventsController.store","tags":["Events"],"description":"Create a new event","responses":{"201":{"description":"The newly created event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to create events"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"}},"required":["title","description","status","minTeamSize","maxTeamSize","slug"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"],"description":"Get a specific event by its slug or UUID","responses":{"200":{"description":"The requested event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Event not found"}}},"put":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroy","tags":["Events"],"description":"Delete an event by its slug or UUID. Requires confirmation of the event slug.","responses":{"204":{"description":"Event deleted successfully"},"403":{"description":"Missing permission to delete this event"},"404":{"description":"Event not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmation":{"type":"string"}},"required":["confirmation"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"],"description":"Get a list of all administrators for an event","responses":{"200":{"description":"A list of administrators for the event","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventAdministrator"}}}}},"403":{"description":"Missing permission to view administrators for this event"},"404":{"description":"Event not found"}},"security":[{"session":[]}]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"],"description":"Create a new administrator for an event","responses":{"201":{"description":"The newly created administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event not found"},"409":{"description":"User is already an administrator of this event"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"number","minimum":0},"permissions":{"type":"number","minimum":0}},"required":["userId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"},"422":{"description":"Provided request data did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"],"description":"Remove administrator from an event","responses":{"204":{"description":"Administrator removed successfully"},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"}},"security":[{"session":[]}]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"]},"put":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"patch":{"operationId":"TeamsController.update","tags":["Teams"],"security":[{"session":[]}]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"]},"get":{"operationId":"TeamsController.index","tags":["Teams"]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"],"security":[{"session":[]}]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"],"security":[{"session":[]}]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"],"security":[{"session":[]}]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"],"security":[{"session":[]}]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"],"security":[{"session":[]}]}},"/events/{event}_id/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"]},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"],"security":[{"session":[]}]}},"/events/{event}_id/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"]},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"],"security":[{"session":[]}]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"],"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"],"security":[{"session":[]}]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"]},"put":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"patch":{"operationId":"TasksController.update","tags":["Tasks"],"security":[{"session":[]}]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"],"security":[{"session":[]}]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"security":[{"session":[]}]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"],"security":[{"session":[]}]}},"/event/{event}_id/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"]}},"/event/{event}_id/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"],"security":[{"session":[]}]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"],"security":[{"session":[]}]}},"/tasks/{task}_id/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"],"security":[{"session":[]}]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"security":[{"session":[]}]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"],"security":[{"session":[]}]}}},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}},"required":["message","rule","field"],"additionalProperties":false}}},"required":["errors"],"additionalProperties":false},"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]},"Event":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"slug":{"example":"best-hackathon-ever","type":"string"},"title":{"example":"Awesome Hackathon","type":"string"},"description":{"example":"A first ever hackathon using a modern platform","type":"string"},"status":{"example":"ACTIVE","enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number"},"maxTeamSize":{"example":4,"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","title","description","status","minTeamSize","maxTeamSize","createdAt","updatedAt"]},"EventAdministrator":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08a","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"userId":{"type":"number"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","eventId","userId","permissions","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"xcontest-session"}},"links":{},"callbacks":{}},"tags":[{"name":"Default","description":"Default tag for all non-classified endpoints"},{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
diff --git a/start/routes.ts b/start/routes.ts
index 159f82c..1f6e8ca 100644
--- a/start/routes.ts
+++ b/start/routes.ts
@@ -34,8 +34,7 @@ import router from '@adonisjs/core/services/router'
 import { middleware } from '#start/kernel'
 import app from '@adonisjs/core/services/app'
 import { UserGuard } from '#utils/permissions'
-import { getHtmlDocument } from '@scalar/core/libs/html-rendering'
-import { generateApiSpec } from '../docs/generator/index.js'
+import { generateApiSpec } from '#openapi/index'
 
 router.get('/', async () => ({
   status: 200,
@@ -55,12 +54,7 @@ router.group(() => {
       // eslint-disable-next-line @unicorn/no-await-expression-member
       response.send((await generateApiSpec({ silent: true })).getSpecAsJson())
   })
-  router.get('/', async ({ response }) => response.send(getHtmlDocument({
-    title: 'xContest API Documentation',
-    url: '/spec/openapi.json',
-    theme: 'purple',
-    darkMode: true,
-  })))
+  router.get('/', async ({ response }) => response.download('docs/spec/spec.html'))
 }).prefix('/spec')
 
 // Temporary endpoint for development

From 859edfb15292df3ac708e1de768d058e34287fb2 Mon Sep 17 00:00:00 2001
From: Oliwier Michalik <oliwier.michalik9@gmail.com>
Date: Thu, 26 Feb 2026 15:16:58 +0100
Subject: [PATCH 5/5] docs: implement openapi documentation for all endpoints
 and models + fix: use qs on validators for query string

---
 app/controllers/hackathons_controller.ts      |  54 +++++----
 app/controllers/organizations_controller.ts   |  65 +++++-----
 app/controllers/scores_controller.ts          |  38 +++---
 app/controllers/tasks_controller.ts           |  53 +++++----
 app/controllers/teams_controller.ts           | 111 ++++++++++++------
 .../hackathon/hackathon_submission_result.ts  |   6 +
 app/models/hackathon/hackathon_task.ts        |   6 +
 .../hackathon/hackathon_task_submission.ts    |   8 ++
 app/models/hackathon/human_score.ts           |   9 ++
 app/models/hackathon/jury_member.ts           |   8 ++
 app/models/media.ts                           |   9 ++
 app/models/organization.ts                    |   9 ++
 app/models/scoring_criterion.ts               |   9 ++
 app/models/sponsor.ts                         |   5 +
 app/models/task/task.ts                       |  33 ++++--
 app/models/task/task_registration.ts          |   5 +
 app/models/team/team.ts                       |   8 +-
 app/models/team/team_invitation.ts            |  11 ++
 app/models/team/team_member.ts                |   7 ++
 app/utils/query.ts                            |   6 +-
 app/validators/common.ts                      |  15 ++-
 app/validators/task.ts                        |   2 +-
 app/validators/team.ts                        |   4 +-
 docs/spec/openapi.json                        |   1 +
 docs/spec/spec.html                           |  24 ++++
 25 files changed, 370 insertions(+), 136 deletions(-)
 create mode 100644 docs/spec/openapi.json
 create mode 100644 docs/spec/spec.html

diff --git a/app/controllers/hackathons_controller.ts b/app/controllers/hackathons_controller.ts
index 9c64723..74c5f67 100644
--- a/app/controllers/hackathons_controller.ts
+++ b/app/controllers/hackathons_controller.ts
@@ -31,11 +31,13 @@ import TaskPolicy from '#policies/task_policy'
 import { createJuryMemberValidator, updateJuryMemberValidator } from '#validators/jury_member'
 import { updateHackathonTaskValidator } from '#validators/task'
 import type { HttpContext } from '@adonisjs/core/http'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
 
 export default class HackathonsController {
-  /**
-   * Show individual hackathon task record
-   */
+  @ApiOperation({ description: 'Get a specific hackathon task by its ID or slug' })
+  @ApiResponse(200, { description: 'The requested hackathon task', data: HackathonTask })
+  @ApiResponse(404, { description: 'Hackathon task not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this task' })
   async showTask({ bouncer, params }: HttpContext) {
     let hackathonTask = await HackathonTask.query()
       .where('id', params.id)
@@ -55,9 +57,11 @@ export default class HackathonsController {
     return hackathonTask
   }
 
-  /**
-   * Handle form submission for the edit action for Hackathon Tasks
-   */
+  @ApiOperation({ description: 'Update a hackathon task by its ID or slug' })
+  @ApiRequest({ validator: updateHackathonTaskValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated hackathon task', data: HackathonTask })
+  @ApiResponse(404, { description: 'Hackathon task not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this task' })
   async updateTask({ bouncer, params, request }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     await bouncer.with(TaskPolicy).authorize('edit', task)
@@ -71,17 +75,21 @@ export default class HackathonsController {
     return hackathonTask
   }
 
-  /**
-   * Display a list of Jury Member resources
-   */
+  @ApiOperation({ description: 'Get a list of jury members for a hackathon task' })
+  @ApiResponse(200, { description: 'A list of jury members for the task', data: [JuryMember] })
+  @ApiResponse(404, { description: 'Task not found' })
   async indexJuryMembers({ params }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     return task.related('juryMembers').query().preload('user')
   }
 
-  /**
-   * Handle form submission for the create action of Jury Member
-   */
+  @ApiOperation({ description: 'Create a new jury member for a hackathon task' })
+  @ApiRequest({ validator: createJuryMemberValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created jury member', data: JuryMember })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage jury members' })
+  @ApiResponse(400, { description: 'Invalid request or jury members can only be assigned to hackathon tasks' })
+  @ApiResponse(409, { description: 'User is already a jury member' })
   async storeJuryMember({ bouncer, params, request, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     const event = await task.related('event').query().firstOrFail()
@@ -114,9 +122,10 @@ export default class HackathonsController {
     return response.created(juryMember)
   }
 
-  /**
-   * Show individual record of Jury Member
-   */
+  @ApiOperation({ description: 'Get a specific jury member by ID' })
+  @ApiResponse(200, { description: 'The requested jury member', data: JuryMember })
+  @ApiResponse(404, { description: 'Jury member not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async showJuryMember({ bouncer, params }: HttpContext) {
     const juryMember = await JuryMember.findOrFail(params.juryMemberId)
     const task = await juryMember.related('task').query().firstOrFail()
@@ -127,9 +136,11 @@ export default class HackathonsController {
     return juryMember
   }
 
-  /**
-   * Update record of Jury Member
-   */
+  @ApiOperation({ description: 'Update a jury member by ID' })
+  @ApiRequest({ validator: updateJuryMemberValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated jury member', data: JuryMember })
+  @ApiResponse(404, { description: 'Jury member not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage jury members' })
   async updateJuryMember({ bouncer, params, request, response }: HttpContext) {
     const juryMember = await JuryMember.findOrFail(params.juryMemberId)
     const task = await juryMember.related('task').query().firstOrFail()
@@ -147,9 +158,10 @@ export default class HackathonsController {
     return juryMember
   }
 
-  /**
-   * Delete record of Jury Member
-   */
+  @ApiOperation({ description: 'Delete a jury member by ID' })
+  @ApiResponse(204, { description: 'Jury member deleted successfully' })
+  @ApiResponse(404, { description: 'Jury member not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage jury members' })
   async destroyJuryMember({ bouncer, params, response }: HttpContext) {
     const juryMember = await JuryMember.findOrFail(params.juryMemberId)
     const task = await juryMember.related('task').query().firstOrFail()
diff --git a/app/controllers/organizations_controller.ts b/app/controllers/organizations_controller.ts
index a4c0917..7b454ea 100644
--- a/app/controllers/organizations_controller.ts
+++ b/app/controllers/organizations_controller.ts
@@ -32,11 +32,12 @@ import {
   updateOrganizationValidator,
 } from '#validators/organization'
 import Task from '#models/task/task'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
 
 export default class OrganizationsController {
-  /**
-   * Display a list of resource
-   */
+  @ApiOperation({ description: 'Get a list of organizations for an event' })
+  @ApiResponse(200, { description: 'A list of organizations', data: [Organization] })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async index({ bouncer, params }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.event_id)
 
@@ -45,9 +46,10 @@ export default class OrganizationsController {
     return event.related('organizations').query()
   }
 
-  /**
-   * Handle form submission for the create action
-   */
+  @ApiOperation({ description: 'Create a new organization for an event' })
+  @ApiRequest({ validator: createOrganizationValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created organization', data: Organization })
+  @ApiResponse(403, { description: 'Missing permission to manage organizations' })
   async store({ bouncer, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(request.param('event_id'))
 
@@ -63,9 +65,10 @@ export default class OrganizationsController {
     return response.created(organization)
   }
 
-  /**
-   * Show individual record
-   */
+  @ApiOperation({ description: 'Get a specific organization by ID' })
+  @ApiResponse(200, { description: 'The requested organization', data: Organization })
+  @ApiResponse(404, { description: 'Organization not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async show({ bouncer, params }: HttpContext) {
     const organization = await Organization.firstOrFail(params.id)
 
@@ -75,9 +78,11 @@ export default class OrganizationsController {
     return organization
   }
 
-  /**
-   * Handle form submission for the edit action
-   */
+  @ApiOperation({ description: 'Update an organization by ID' })
+  @ApiRequest({ validator: updateOrganizationValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated organization', data: Organization })
+  @ApiResponse(404, { description: 'Organization not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage organizations' })
   async update({ bouncer, params, request }: HttpContext) {
     const organization = await Organization.findOrFail(params.id)
 
@@ -91,9 +96,10 @@ export default class OrganizationsController {
     return organization
   }
 
-  /**
-   * Delete record
-   */
+  @ApiOperation({ description: 'Delete an organization by ID' })
+  @ApiResponse(204, { description: 'Organization deleted successfully' })
+  @ApiResponse(404, { description: 'Organization not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage organizations' })
   async destroy({ bouncer, params, response }: HttpContext) {
     const organization = await Organization.findOrFail(params.id)
 
@@ -104,18 +110,21 @@ export default class OrganizationsController {
     return response.noContent()
   }
 
-  /**
-   * Display a list of Sponsor resources
-   */
+  @ApiOperation({ description: 'Get a list of sponsors for a task' })
+  @ApiResponse(200, { description: 'A list of sponsors for the task', data: [Sponsor] })
+  @ApiResponse(404, { description: 'Task not found' })
   async indexSponsors({ params }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     return task.related('sponsors').query().preload('organization')
   }
 
 
-  /**
-   * Handle form submission for the create action of Sponsor
-   */
+  @ApiOperation({ description: 'Create a new sponsor for a task' })
+  @ApiRequest({ validator: createSponsorValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created sponsor', data: Sponsor })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage sponsors' })
+  @ApiResponse(400, { description: 'Organization does not belong to the same event' })
   async storeSponsor({ bouncer, params, request, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     const event = await task.related('event').query().firstOrFail()
@@ -137,9 +146,10 @@ export default class OrganizationsController {
     return response.created(sponsor)
   }
 
-  /**
-   * Show individual record of Sponsor
-   */
+  @ApiOperation({ description: 'Get a specific sponsor by ID' })
+  @ApiResponse(200, { description: 'The requested sponsor', data: Sponsor })
+  @ApiResponse(404, { description: 'Sponsor not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async showSponsor({ bouncer, params }: HttpContext) {
     const sponsor = await Sponsor.findOrFail(params.sponsorId)
     const task = await sponsor.related('task').query().firstOrFail()
@@ -150,9 +160,10 @@ export default class OrganizationsController {
     return sponsor
   }
 
-  /**
-   * Delete record of Sponsor
-   */
+  @ApiOperation({ description: 'Delete a sponsor by ID' })
+  @ApiResponse(204, { description: 'Sponsor deleted successfully' })
+  @ApiResponse(404, { description: 'Sponsor not found' })
+  @ApiResponse(403, { description: 'Missing permission to manage sponsors' })
   async destroySponsor({ bouncer, params, response }: HttpContext) {
     const sponsor = await Sponsor.findOrFail(params.sponsorId)
     const task = await sponsor.related('task').query().firstOrFail()
diff --git a/app/controllers/scores_controller.ts b/app/controllers/scores_controller.ts
index eba1c91..96ccf2f 100644
--- a/app/controllers/scores_controller.ts
+++ b/app/controllers/scores_controller.ts
@@ -26,11 +26,13 @@ import Task from '#models/task/task'
 import TaskPolicy from '#policies/task_policy'
 import { createScoringCriterionValidator, updateScoringCriterionValidator } from '#validators/score'
 import type { HttpContext } from '@adonisjs/core/http'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
 
 export default class ScoresController {
-  /**
-   * Display a list of ScoringCriterion resources
-   */
+  @ApiOperation({ description: 'Get a list of scoring criteria for a task' })
+  @ApiResponse(200, { description: 'A list of scoring criteria', data: [ScoringCriterion] })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this task' })
   async indexCriteria({ bouncer, params }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.task_id)
     await bouncer.with(TaskPolicy).authorize('view', task)
@@ -39,9 +41,11 @@ export default class ScoresController {
   }
 
 
-  /**
-   * Handle form submission for the create action of ScoringCriterion
-   */
+  @ApiOperation({ description: 'Create a new scoring criterion for a task' })
+  @ApiRequest({ validator: createScoringCriterionValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created scoring criterion', data: ScoringCriterion })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this task' })
   async storeCriteria({ bouncer, params, request, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.task_id)
     await bouncer.with(TaskPolicy).authorize('edit', task)
@@ -53,9 +57,10 @@ export default class ScoresController {
     return response.created(criterion)
   }
 
-  /**
-   * Show an individual record of ScoringCriterion
-   */
+  @ApiOperation({ description: 'Get a specific scoring criterion by ID' })
+  @ApiResponse(200, { description: 'The requested scoring criterion', data: ScoringCriterion })
+  @ApiResponse(404, { description: 'Scoring criterion not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this task' })
   async showCriteria({ bouncer, params }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.task_id)
     await bouncer.with(TaskPolicy).authorize('view', task)
@@ -66,9 +71,11 @@ export default class ScoresController {
       .firstOrFail()
   }
 
-  /**
-   * Handle form submission for the edit action of a ScoringCriterion
-   */
+  @ApiOperation({ description: 'Update a scoring criterion by ID' })
+  @ApiRequest({ validator: updateScoringCriterionValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated scoring criterion', data: ScoringCriterion })
+  @ApiResponse(404, { description: 'Scoring criterion not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this task' })
   async updateCriteria({ bouncer, params, request }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.task_id)
     await bouncer.with(TaskPolicy).authorize('edit', task)
@@ -86,9 +93,10 @@ export default class ScoresController {
     return criterion
   }
 
-  /**
-   * Delete a ScoringCriterion record
-   */
+  @ApiOperation({ description: 'Delete a scoring criterion by ID' })
+  @ApiResponse(204, { description: 'Scoring criterion deleted successfully' })
+  @ApiResponse(404, { description: 'Scoring criterion not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this task' })
   async destroyCriteria({ bouncer, params, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.task_id)
     await bouncer.with(TaskPolicy).authorize('edit', task)
diff --git a/app/controllers/tasks_controller.ts b/app/controllers/tasks_controller.ts
index f48167a..74960f5 100644
--- a/app/controllers/tasks_controller.ts
+++ b/app/controllers/tasks_controller.ts
@@ -36,11 +36,12 @@ import TeamPolicy from '#policies/team_policy'
 import { DateTime } from 'luxon'
 import TaskRegistration from '#models/task/task_registration'
 import EventPolicy from '#policies/event_policy'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
 
 export default class TasksController {
-  /**
-   * Display a list of tasks for an event
-   */
+  @ApiOperation({ description: 'Get a list of tasks for an event' })
+  @ApiResponse(200, { description: 'A list of tasks', data: [Task] })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async index({ bouncer, params }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.event_id)
 
@@ -55,9 +56,10 @@ export default class TasksController {
     return Promise.all(tasks.map(async (task) => getTaskByType(task)))
   }
 
-  /**
-   * Handle form submission for the creation action
-   */
+  @ApiOperation({ description: 'Create a new task for an event' })
+  @ApiRequest({ validator: createTaskValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created task', data: Task })
+  @ApiResponse(403, { description: 'Missing permission to create tasks' })
   async store({ bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.event_id)
     await bouncer.with(TaskPolicy).authorize('create', event)
@@ -106,9 +108,10 @@ export default class TasksController {
     return response.created(task)
   }
 
-  /**
-   * Show individual record
-   */
+  @ApiOperation({ description: 'Get a specific task by its ID or slug' })
+  @ApiResponse(200, { description: 'The requested task', data: Task })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this task' })
   async show({ bouncer, params }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     await bouncer.with(TaskPolicy).authorize('view', task)
@@ -116,9 +119,11 @@ export default class TasksController {
     return getTaskByType(task)
   }
 
-  /**
-   * Handle form submission for the edit action
-   */
+  @ApiOperation({ description: 'Update a task by its ID or slug' })
+  @ApiRequest({ validator: updateTaskValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated task', data: Task })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this task' })
   async update({ bouncer, params, request }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     await bouncer.with(TaskPolicy).authorize('edit', task)
@@ -133,9 +138,10 @@ export default class TasksController {
     return task
   }
 
-  /**
-   * Delete record
-   */
+  @ApiOperation({ description: 'Delete a task by its ID or slug' })
+  @ApiResponse(204, { description: 'Task deleted successfully' })
+  @ApiResponse(404, { description: 'Task not found' })
+  @ApiResponse(403, { description: 'Missing permission to delete this task' })
   async destroy({ bouncer, params, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.id)
     await bouncer.with(TaskPolicy).authorize('delete', task)
@@ -144,9 +150,13 @@ export default class TasksController {
     return response.noContent()
   }
 
-  /**
-   * Handle form submission for the create action of task registration
-   */
+  @ApiOperation({ description: 'Register a team to a task' })
+  @ApiRequest({ validator: createTaskRegistrationValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created task registration', data: TaskRegistration })
+  @ApiResponse(404, { description: 'Task or team not found' })
+  @ApiResponse(400, { description: 'Team does not belong to the same event or registration is not open' })
+  @ApiResponse(403, { description: 'Missing permission to register team' })
+  @ApiResponse(409, { description: 'Team is already registered to the task' })
   async storeTaskRegistration({ bouncer, params, request, response }: HttpContext) {
     const task = await Task.findByUuidOrSlug(params.taskId)
 
@@ -199,9 +209,10 @@ export default class TasksController {
     return response.created(taskRegistration)
   }
 
-  /**
-   * Delete record of Task Registration
-   */
+  @ApiOperation({ description: 'Unregister a team from a task' })
+  @ApiResponse(204, { description: 'Task registration deleted successfully' })
+  @ApiResponse(404, { description: 'Task registration not found' })
+  @ApiResponse(403, { description: 'Missing permission to unregister team' })
   async destroyTaskRegistration({ bouncer, params, response }: HttpContext) {
     const taskRegistration = await TaskRegistration.findOrFail(params.id)
 
diff --git a/app/controllers/teams_controller.ts b/app/controllers/teams_controller.ts
index f5c089b..2cd3091 100644
--- a/app/controllers/teams_controller.ts
+++ b/app/controllers/teams_controller.ts
@@ -35,35 +35,38 @@ import TeamPolicy from '#policies/team_policy'
 import db from '@adonisjs/lucid/services/db'
 import { TeamMemberGuard } from '#utils/permissions'
 import EventPolicy from '#policies/event_policy'
-import { confirmationValidator, paramsIdValidator } from '#validators/common'
+import { commonQueryValidator, confirmationValidator, paramsIdValidator } from '#validators/common'
 import { applyQueryFilters } from '#utils/query'
 import Task from '#models/task/task'
 import { generateMemorableToken, generateSecureToken, invitationValidity } from '#utils/teams'
 import TeamInvitation from '#models/team/team_invitation'
 import InvitationSent from '#events/invitation_sent'
 import env from '#start/env'
+import { ApiOperation, ApiRequest, ApiResponse } from '#openapi/decorators'
+import { merged, paginated } from '#openapi/tools'
+import TeamMember from '#models/team/team_member'
 
 export default class TeamsController {
-  /**
-   * Display a list of resource
-   */
+  @ApiOperation({ description: 'Get a list of teams for an event' })
+  @ApiRequest({ validator: commonQueryValidator })
+  @ApiResponse(200, { description: 'A list of teams', data: paginated(Team) })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async index({ bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.event_id)
     await bouncer.with(EventPolicy).authorize('view', event)
 
-    return applyQueryFilters(
-      event.related('teams').query(),
-      {
-        request, response,
-        searchColumn: 'name',
-        allowedColumns: ['name', 'created_at'],
-      },
-    )
+    return applyQueryFilters(event.related('teams').query(), {
+      request,
+      response,
+      searchColumn: 'name',
+      allowedColumns: ['name', 'created_at'],
+    })
   }
 
-  /**
-   * Handle form submission for the creation action
-   */
+  @ApiOperation({ description: 'Create a new team in an event' })
+  @ApiRequest({ validator: createTeamValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created team', data: Team })
+  @ApiResponse(403, { description: 'Missing permission or invalid access code' })
   async store({ auth, bouncer, params, request, response }: HttpContext) {
     const event = await Event.findByUuidOrSlug(params.event_id)
     const { accessCode, ...payload } = await request.validateUsing(createTeamValidator, {
@@ -89,9 +92,12 @@ export default class TeamsController {
         .where('autoregister', true)
 
       for (const task of autoregisterTasks)
-        await task.related('registrations').create({
-          teamId: newTeam.id,
-        }, { client: trx })
+        await task.related('registrations').create(
+          {
+            teamId: newTeam.id,
+          },
+          { client: trx },
+        )
 
       return newTeam
     })
@@ -99,9 +105,13 @@ export default class TeamsController {
     return response.created(team)
   }
 
-  /**
-   * Show individual record
-   */
+  @ApiOperation({ description: 'Get a specific team by ID' })
+  @ApiResponse(200, {
+    description: 'The requested team',
+    data: merged(Team, { members: [TeamMember] }),
+  })
+  @ApiResponse(404, { description: 'Team not found' })
+  @ApiResponse(403, { description: 'Missing permission to view this event' })
   async show({ bouncer, request }: HttpContext) {
     const { params } = await request.validateUsing(paramsIdValidator)
     const team = await Team.findOrFail(params.id)
@@ -111,9 +121,11 @@ export default class TeamsController {
     return team
   }
 
-  /**
-   * Handle form submission for the edit action
-   */
+  @ApiOperation({ description: 'Update a team by ID' })
+  @ApiRequest({ validator: updateTeamValidator, withResponse: true })
+  @ApiResponse(200, { description: 'The updated team', data: Team })
+  @ApiResponse(404, { description: 'Team not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this team' })
   async update({ bouncer, request }: HttpContext) {
     const { params } = await request.validateUsing(paramsIdValidator)
     const team = await Team.findOrFail(params.id)
@@ -132,9 +144,11 @@ export default class TeamsController {
     return team
   }
 
-  /**
-   * Delete record
-   */
+  @ApiOperation({ description: 'Delete a team by ID. Requires confirmation of the team name.' })
+  @ApiRequest({ validator: confirmationValidator, withResponse: true })
+  @ApiResponse(204, { description: 'Team deleted successfully' })
+  @ApiResponse(404, { description: 'Team not found' })
+  @ApiResponse(403, { description: 'Missing permission to delete this team' })
   async destroy({ bouncer, request, response }: HttpContext) {
     const { params } = await request.validateUsing(paramsIdValidator)
     const team = await Team.findOrFail(params.id)
@@ -151,7 +165,11 @@ export default class TeamsController {
     return response.noContent()
   }
 
-  // Kick team member by member uuid
+  @ApiOperation({ description: 'Kick a member from a team' })
+  @ApiRequest({ validator: kickMemberValidator, withResponse: true })
+  @ApiResponse(204, { description: 'Team member removed successfully' })
+  @ApiResponse(404, { description: 'Team or member not found' })
+  @ApiResponse(403, { description: 'Missing permission to kick this member' })
   async kickMember({ bouncer, request, response }: HttpContext) {
     const { member, params } = await request.validateUsing(kickMemberValidator)
     const team = await Team.findOrFail(params.id)
@@ -161,7 +179,11 @@ export default class TeamsController {
     return response.noContent()
   }
 
-  // Create a new invite
+  @ApiOperation({ description: 'Create a new team invitation' })
+  @ApiRequest({ validator: teamInvitationValidator, withResponse: true })
+  @ApiResponse(201, { description: 'The newly created invitation', data: TeamInvitation })
+  @ApiResponse(404, { description: 'Team not found' })
+  @ApiResponse(403, { description: 'Missing permission to invite to this team' })
   async storeInvite({ auth, bouncer, request }: HttpContext) {
     const { params } = await request.validateUsing(paramsIdValidator)
     const team = await Team.findOrFail(params.id)
@@ -178,7 +200,10 @@ export default class TeamsController {
     return invitation
   }
 
-  // List all invites for the team
+  @ApiOperation({ description: 'Get a list of team invitations for a team' })
+  @ApiResponse(200, { description: 'A list of team invitations', data: [TeamInvitation] })
+  @ApiResponse(404, { description: 'Team not found' })
+  @ApiResponse(403, { description: 'Missing permission to edit this team' })
   async indexInvites({ bouncer, request }: HttpContext) {
     const { params } = await request.validateUsing(paramsIdValidator)
     const team = await Team.findOrFail(params.id)
@@ -187,7 +212,12 @@ export default class TeamsController {
     return TeamInvitation.fetchTeamSyncExpirations(team)
   }
 
-  // List all invitations for user
+  @ApiOperation({ description: 'Get a list of pending team invitations for the current user' })
+  @ApiRequest({ validator: commonQueryValidator })
+  @ApiResponse(200, {
+    description: 'A list of team invitations for the user',
+    data: paginated(TeamInvitation),
+  })
   async indexUserInvites({ auth, request, response }: HttpContext) {
     const user = auth.getUserOrFail()
     await TeamInvitation.syncUserExpirations(user)
@@ -197,7 +227,8 @@ export default class TeamsController {
         .where('invitee_email', user.email)
         .leftJoin('teams', 'team_invitations.team_id', 'teams.id'),
       {
-        request, response,
+        request,
+        response,
         searchColumn: 'teams.name',
         allowedColumns: ['created_at', 'teams.name', 'token'],
         defaultTable: 'team_invitations',
@@ -205,14 +236,22 @@ export default class TeamsController {
     )
   }
 
-  // Accept/Decline an invitation
+  @ApiOperation({ description: 'Accept or decline a team invitation' })
+  @ApiRequest({ validator: teamInvitationResponseValidator, withResponse: true })
+  @ApiResponse(200, {
+    description: 'Invitation responded successfully',
+    data: { invitation: TeamInvitation, member: TeamMember },
+  })
+  @ApiResponse(404, { description: 'Invitation not found' })
+  @ApiResponse(403, { description: 'Missing permission to respond to this invitation' })
   async respondToInvite({ auth, bouncer, request, response }: HttpContext) {
-    const { action, params } = await request.validateUsing(teamInvitationResponseValidator, {
+    const { qs, params } = await request.validateUsing(teamInvitationResponseValidator, {
       data: {
-        ...request.qs(),
+        qs: request.qs(),
         params: request.params(),
       },
     })
+    const action = qs.action as 'ACCEPT' | 'DECLINE' | undefined
     const invitation = await TeamInvitation.query()
       .where('token', params.id)
       .orderByRaw("CASE WHEN status = 'PENDING' THEN 0 ELSE 1 END ASC")
@@ -222,7 +261,7 @@ export default class TeamsController {
     const user = auth.getUserOrFail()
     const member = await db.transaction(async (trx) => {
       invitation.useTransaction(trx)
-      invitation.status = (!action || action === 'ACCEPT') ? 'ACCEPTED' : 'DECLINED'
+      invitation.status = !action || action === 'ACCEPT' ? 'ACCEPTED' : 'DECLINED'
       await invitation.save()
 
       if (invitation.status === 'ACCEPTED') {
diff --git a/app/models/hackathon/hackathon_submission_result.ts b/app/models/hackathon/hackathon_submission_result.ts
index 710d65c..12bed60 100644
--- a/app/models/hackathon/hackathon_submission_result.ts
+++ b/app/models/hackathon/hackathon_submission_result.ts
@@ -27,21 +27,27 @@ import { BaseModel, beforeCreate, belongsTo, column, hasMany } from '@adonisjs/l
 import type { BelongsTo, HasMany } from '@adonisjs/lucid/types/relations'
 import HackathonTaskSubmission from '#models/hackathon/hackathon_task_submission'
 import HumanScore from '#models/hackathon/human_score'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class HackathonSubmissionResult extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskSubmissionId: string
 
   @column()
+  @ApiColumn(Boolean, { example: false })
   declare isDisqualified: boolean
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => HackathonTaskSubmission, { foreignKey: 'taskSubmissionId' })
diff --git a/app/models/hackathon/hackathon_task.ts b/app/models/hackathon/hackathon_task.ts
index 8b3b53d..98810df 100644
--- a/app/models/hackathon/hackathon_task.ts
+++ b/app/models/hackathon/hackathon_task.ts
@@ -26,21 +26,27 @@ import { DateTime } from 'luxon'
 import { BaseModel, beforeCreate, belongsTo, column } from '@adonisjs/lucid/orm'
 import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import Task from '#models/task/task'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class HackathonTask extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskId: string
 
   @column()
+  @ApiColumn(String, { example: 'https://example.com/requirements.pdf' })
   declare requirementsDocumentUrl: string
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Task)
diff --git a/app/models/hackathon/hackathon_task_submission.ts b/app/models/hackathon/hackathon_task_submission.ts
index 108b174..24bba0d 100644
--- a/app/models/hackathon/hackathon_task_submission.ts
+++ b/app/models/hackathon/hackathon_task_submission.ts
@@ -27,27 +27,35 @@ import { BaseModel, beforeCreate, belongsTo, column, hasOne } from '@adonisjs/lu
 import type { BelongsTo, HasOne } from '@adonisjs/lucid/types/relations'
 import TaskRegistration from '#models/task/task_registration'
 import HackathonSubmissionResult from '#models/hackathon/hackathon_submission_result'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class HackathonTaskSubmission extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskRegistrationId: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'This is our submission description' })
   declare description: string | null
 
   @column()
+  @ApiColumn(String, { required: false, example: 'https://github.com/user/repo' })
   declare repositoryUrl: string | null
 
   @column()
+  @ApiColumn(String, { example: 'ACTIVE' })
   declare status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED'
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => TaskRegistration)
diff --git a/app/models/hackathon/human_score.ts b/app/models/hackathon/human_score.ts
index f5937ff..1a2d376 100644
--- a/app/models/hackathon/human_score.ts
+++ b/app/models/hackathon/human_score.ts
@@ -28,30 +28,39 @@ import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import JuryMember from '#models/hackathon/jury_member'
 import HackathonSubmissionResult from '#models/hackathon/hackathon_submission_result'
 import ScoringCriterion from '#models/scoring_criterion'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class HumanScore extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare juryMemberId: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare submissionResultId: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare criterionId: string
 
   @column()
+  @ApiColumn(Number, { example: 85 })
   declare score: number
 
   @column()
+  @ApiColumn(String, { example: 'Great implementation with good code quality' })
   declare description: string
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => JuryMember)
diff --git a/app/models/hackathon/jury_member.ts b/app/models/hackathon/jury_member.ts
index 2d1fc77..9aa8863 100644
--- a/app/models/hackathon/jury_member.ts
+++ b/app/models/hackathon/jury_member.ts
@@ -29,27 +29,35 @@ import User from '#models/user'
 import Task from '#models/task/task'
 import Organization from '#models/organization'
 import HumanScore from '#models/hackathon/human_score'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class JuryMember extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'Senior judge with 10 years experience' })
   declare description: string
 
   @column()
+  @ApiColumn(Number, { example: 1 })
   declare userId: number
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskId: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare organizationId: string | null
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => User)
diff --git a/app/models/media.ts b/app/models/media.ts
index e935c58..350f580 100644
--- a/app/models/media.ts
+++ b/app/models/media.ts
@@ -24,30 +24,39 @@
 import { randomUUID } from 'node:crypto'
 import { DateTime } from 'luxon'
 import { BaseModel, beforeCreate, column } from '@adonisjs/lucid/orm'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class Media extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare relatedId: string
 
   @column()
+  @ApiColumn(String, { example: 'Project screenshot' })
   declare description: string
 
   @column()
+  @ApiColumn(String, { example: 'IMAGE' })
   declare mediaType: 'IMAGE' | 'VIDEO' | 'DOCUMENT' | 'LINK'
 
   @column()
+  @ApiColumn(String, { example: 'https://example.com/image.png' })
   declare url: string
 
   @column()
+  @ApiColumn(Number, { example: 1 })
   declare galleryIndex: number
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @beforeCreate()
diff --git a/app/models/organization.ts b/app/models/organization.ts
index 18695eb..84de556 100644
--- a/app/models/organization.ts
+++ b/app/models/organization.ts
@@ -28,33 +28,42 @@ import type { BelongsTo, HasMany } from '@adonisjs/lucid/types/relations'
 import JuryMember from '#models/hackathon/jury_member'
 import Sponsor from '#models/sponsor'
 import Event from '#models/event/event'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class Organization extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'Acme Corporation' })
   declare name: string
 
   @column()
+  @ApiColumn(String, { example: 'A leading corporation' })
   declare description: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'https://example.com/logo.png' })
   declare logoUrl: string | null
 
   @column()
+  @ApiColumn(String, { required: false, example: 'https://example.com' })
   declare websiteUrl: string | null
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare eventId: string
 
   @belongsTo(() => Event)
   declare event: BelongsTo<typeof Event>
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @hasMany(() => JuryMember)
diff --git a/app/models/scoring_criterion.ts b/app/models/scoring_criterion.ts
index 1120e4a..60ae2b1 100644
--- a/app/models/scoring_criterion.ts
+++ b/app/models/scoring_criterion.ts
@@ -27,30 +27,39 @@ import { BaseModel, beforeCreate, belongsTo, column, hasMany } from '@adonisjs/l
 import type { BelongsTo, HasMany } from '@adonisjs/lucid/types/relations'
 import Task from '#models/task/task'
 import HumanScore from '#models/hackathon/human_score'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class ScoringCriterion extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskId: string
 
   @column()
+  @ApiColumn(String, { example: 'Code Quality' })
   declare category: string
 
   @column()
+  @ApiColumn(String, { required: false, example: 'Assessment of code quality and best practices' })
   declare description: string | null
 
   @column()
+  @ApiColumn(Number, { example: 100 })
   declare maximumScore: number
 
   @column()
+  @ApiColumn(Number, { example: 1.5 })
   declare weight: number
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Task)
diff --git a/app/models/sponsor.ts b/app/models/sponsor.ts
index 2df1de0..5a36f28 100644
--- a/app/models/sponsor.ts
+++ b/app/models/sponsor.ts
@@ -27,18 +27,23 @@ import { BaseModel, beforeCreate, belongsTo, column } from '@adonisjs/lucid/orm'
 import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import Task from '#models/task/task'
 import Organization from '#models/organization'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class Sponsor extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskId: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare organizationId: string
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @belongsTo(() => Task)
diff --git a/app/models/task/task.ts b/app/models/task/task.ts
index d5a1a45..bae30c5 100644
--- a/app/models/task/task.ts
+++ b/app/models/task/task.ts
@@ -33,54 +33,71 @@ import JuryMember from '#models/hackathon/jury_member'
 import Sponsor from '#models/sponsor'
 import { uuidV4Regex } from '#validators/common'
 import { Exception } from '@adonisjs/core/exceptions'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class Task extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare eventId: string
 
   @column()
+  @ApiColumn(String, { example: 'awesome-hackathon-task' })
   declare slug: string
 
   @column()
+  @ApiColumn(String, { example: 'Awesome Hackathon Task' })
   declare title: string
 
   @column()
+  @ApiColumn(String, { example: 'Build an awesome application' })
   declare description: string
 
   @column()
+  @ApiColumn(String, { example: 'HACKATHON' })
   declare taskType: 'HACKATHON' | 'CTF' | 'ALGO'
 
   @column()
+  @ApiColumn(String, { example: 'ACTIVE' })
   declare status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED'
 
   @column()
+  @ApiColumn(Boolean, { example: false })
   declare autoregister: boolean
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare resultsPublishedAt: DateTime | null
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare registrationStartAt: DateTime | null
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare registrationEndAt: DateTime | null
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare detailsRevealAt: DateTime | null
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare submissionsStartAt: DateTime | null
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare submissionsEndAt: DateTime | null
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Event)
@@ -109,17 +126,17 @@ export default class Task extends BaseModel {
   public static async findByUuidOrSlug(value: string) {
     const task = await Task.query()
       .where((q) => {
-        if (uuidV4Regex.test(value)) 
+        if (uuidV4Regex.test(value))
           q.where('id', value)
-        else 
+        else
           q.where('slug', value)
       })
       .first()
-  
-    if (!task) 
+
+    if (!task)
       throw new Exception('Task not found', { status: 404, code: 'E_TASK_NOT_FOUND' })
-    
-  
+
+
     return task
   }
 
@@ -127,7 +144,7 @@ export default class Task extends BaseModel {
     const dateFields = ['resultsPublishedAt', 'registrationStartAt', 'registrationEndAt', 'detailsRevealAt', 'submissionsStartAt', 'submissionsEndAt'] as const
     const parsedPayload: Record<string, any> = { ...payload }
 
-    for (const field of dateFields) 
+    for (const field of dateFields)
       if (field in payload) {
         const value = payload[field]
         switch (true) {
@@ -144,7 +161,7 @@ export default class Task extends BaseModel {
             throw new Exception(`Invalid date format for ${field}`, { status: 422, code: 'E_INVALID_DATE' })
         }
       }
-    
+
 
     return parsedPayload as Partial<Task>
   }
diff --git a/app/models/task/task_registration.ts b/app/models/task/task_registration.ts
index 348069b..44a6a6a 100644
--- a/app/models/task/task_registration.ts
+++ b/app/models/task/task_registration.ts
@@ -28,18 +28,23 @@ import type { BelongsTo, HasMany } from '@adonisjs/lucid/types/relations'
 import Team from '#models/team/team'
 import Task from '#models/task/task'
 import HackathonTaskSubmission from '#models/hackathon/hackathon_task_submission'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class TaskRegistration extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare teamId: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare taskId: string
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @belongsTo(() => Team)
diff --git a/app/models/team/team.ts b/app/models/team/team.ts
index bb6002e..e297d18 100644
--- a/app/models/team/team.ts
+++ b/app/models/team/team.ts
@@ -29,21 +29,27 @@ import Event from '#models/event/event'
 import TeamMember from '#models/team/team_member'
 import TeamInvitation from '#models/team/team_invitation'
 import TaskRegistration from '#models/task/task_registration'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class Team extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
-  @column({ serializeAs: null })
+  @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare eventId: string
 
   @column()
+  @ApiColumn(String, { example: 'Team Awesome' })
   declare name: string
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Event)
diff --git a/app/models/team/team_invitation.ts b/app/models/team/team_invitation.ts
index 8d901fc..8fd5b85 100644
--- a/app/models/team/team_invitation.ts
+++ b/app/models/team/team_invitation.ts
@@ -27,33 +27,44 @@ import { BaseModel, beforeCreate, beforeSave, belongsTo, column } from '@adonisj
 import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import Team from '#models/team/team'
 import User from '#models/user'
+import { ApiColumn } from '#openapi/decorators'
+import vine from '@vinejs/vine'
 
 export default class TeamInvitation extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare teamId: string
 
   @column()
+  @ApiColumn(Number, { example: 1 })
   declare inviterId: number
 
   @column()
+  @ApiColumn(String, { required: false, example: 'user@example.com' })
   declare inviteeEmail: string | null
 
   @column()
+  @ApiColumn(String, { example: 'secure-token-here' })
   declare token: string
 
   @column({})
+  @ApiColumn(vine.enum(['PENDING', 'ACCEPTED', 'DECLINED', 'FAILED', 'EXPIRED']), { example: 'PENDING' })
   declare status: 'PENDING' | 'ACCEPTED' | 'DECLINED' | 'FAILED' | 'EXPIRED'
 
   @column.dateTime()
+  @ApiColumn(String, { required: false, format: 'date-time' })
   declare expiresAt: DateTime | null
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Team)
diff --git a/app/models/team/team_member.ts b/app/models/team/team_member.ts
index 0b20001..3472dee 100644
--- a/app/models/team/team_member.ts
+++ b/app/models/team/team_member.ts
@@ -28,24 +28,31 @@ import type { BelongsTo } from '@adonisjs/lucid/types/relations'
 import Team from '#models/team/team'
 import User from '#models/user'
 import type { Mask, TeamMemberPermissions } from '#utils/permissions'
+import { ApiColumn } from '#openapi/decorators'
 
 export default class TeamMember extends BaseModel {
   @column({ isPrimary: true })
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare id: string
 
   @column()
+  @ApiColumn(String, { example: 'd62a1715-6b7a-4b40-8bdd-4a10f2ceb08c' })
   declare teamId: string
 
   @column()
+  @ApiColumn(Number, { example: 1 })
   declare userId: number
 
   @column()
+  @ApiColumn(Number, { format: 'binary' })
   declare permissions: Mask<typeof TeamMemberPermissions>
 
   @column.dateTime({ autoCreate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare createdAt: DateTime
 
   @column.dateTime({ autoCreate: true, autoUpdate: true })
+  @ApiColumn(String, { format: 'date-time' })
   declare updatedAt: DateTime | null
 
   @belongsTo(() => Team)
diff --git a/app/utils/query.ts b/app/utils/query.ts
index 6919cd7..32119b4 100644
--- a/app/utils/query.ts
+++ b/app/utils/query.ts
@@ -47,8 +47,10 @@ export async function applyQueryFilters<Q extends ModelQueryBuilderContract<any>
     defaultTable?: string
   },
 ) {
-  const params = await request.validateUsing(commonQueryValidator, {
-    data: request.qs(),
+  const { qs: params } = await request.validateUsing(commonQueryValidator, {
+    data: {
+      qs: request.qs(),
+    },
   })
 
   // Search query
diff --git a/app/validators/common.ts b/app/validators/common.ts
index 3ffa5bf..c9f58ce 100644
--- a/app/validators/common.ts
+++ b/app/validators/common.ts
@@ -68,12 +68,21 @@ export const commonQuerySchema = vine.object({
       vine
         .string()
         .trim()
-        .regex(/^[^:]+:[><=]?[^:]+$/),
+        .regex(/^[^:]+:[><=!~]{1,2}[^:]+$/),
     )
-    .optional(),
+    .optional()
+    .meta({
+      description: `
+        Custom filter in a format key:[op]value.
+        For example name:~Adam will find every name that contains Adam.
+        Supported ops: <, >, <=, >=, =, !, ~
+      `.trim(),
+    }),
 })
 
-export const commonQueryValidator = vine.create(commonQuerySchema)
+export const commonQueryValidator = vine.create(vine.object({
+  qs: commonQuerySchema,
+}))
 
 export const paramsIdValidator = vine.create(
   vine.object({
diff --git a/app/validators/task.ts b/app/validators/task.ts
index 6dba5e6..1263779 100644
--- a/app/validators/task.ts
+++ b/app/validators/task.ts
@@ -30,7 +30,7 @@ const taskCoreSchema = {
   description: vine.string().trim().escape(),
   taskType: vine.enum(['HACKATHON', 'CTF', 'ALGO'] as const),
   status: vine.enum(['DRAFT', 'ACTIVE', 'ARCHIVED'] as const),
-  autoregister: vine.boolean(),
+  autoregister: vine.boolean({ strict: true }),
 }
 
 const taskDateFields = () => ({
diff --git a/app/validators/team.ts b/app/validators/team.ts
index 39f1123..681e6c8 100644
--- a/app/validators/team.ts
+++ b/app/validators/team.ts
@@ -71,7 +71,9 @@ export const teamInvitationValidator = vine.create(
 
 export const teamInvitationResponseValidator = vine.create(
   vine.object({
-    action: vine.enum(['ACCEPT', 'REJECT']).optional(),
+    qs: vine.object({
+      action: vine.enum(['ACCEPT', 'REJECT']).optional(),
+    }),
     params: vine.object({
       id: vine.string().minLength(16).maxLength(45),
     }),
diff --git a/docs/spec/openapi.json b/docs/spec/openapi.json
new file mode 100644
index 0000000..af3e043
--- /dev/null
+++ b/docs/spec/openapi.json
@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"xContest REST API","description":"Specification document for REST API component of xContest platform","version":"1.0.0"},"paths":{"/auth/{provider}/redirect":{"get":{"operationId":"AuthController.redirect","tags":["Auth"],"description":"Redirects to the social provider for authentication","responses":{"307":{"description":"Redirects to the social provider"}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/{provider}/callback":{"get":{"operationId":"AuthController.callback","tags":["Auth"],"description":"Handles the callback from the social provider","responses":{"307":{"description":"Redirects to the status page"}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"enum":["discord","github"]}}]}},"/auth/register":{"post":{"operationId":"AuthController.register","tags":["Auth"],"description":"Registers a new user with email and password","responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":3,"maxLength":16},"name":{"type":"string","minLength":3,"maxLength":32},"surname":{"type":"string","minLength":3,"maxLength":32},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}},"required":["nickname","email","password"],"additionalProperties":false}}}}}},"/auth/login":{"post":{"operationId":"AuthController.login","tags":["Auth"],"description":"Logs in a user with email and password","responses":{"200":{"description":"User logged in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/auth/logout":{"post":{"operationId":"AuthController.logout","tags":["Auth"],"description":"Logs out the current user","responses":{"200":{"description":"User logged out successfully"}},"security":[{"session":[]}]}},"/events":{"get":{"operationId":"EventsController.index","tags":["Events"],"description":"Get a list of all active events","responses":{"200":{"description":"A list of active events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"post":{"operationId":"EventsController.store","tags":["Events"],"description":"Create a new event","responses":{"201":{"description":"The newly created event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to create events"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"}},"required":["title","description","status","minTeamSize","maxTeamSize","slug"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}":{"get":{"operationId":"EventsController.show","tags":["Events"],"description":"Get a specific event by its slug or UUID","responses":{"200":{"description":"The requested event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Event not found"}}},"put":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.update","tags":["Events"],"description":"Update an existing event by its slug or UUID","responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"403":{"description":"Missing permission to edit this event"},"404":{"description":"Event not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number","minimum":1},"maxTeamSize":{"type":"number","minimum":1},"slug":{"type":"string"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroy","tags":["Events"],"description":"Delete an event by its slug or UUID. Requires confirmation of the event slug.","responses":{"204":{"description":"Event deleted successfully"},"403":{"description":"Missing permission to delete this event"},"404":{"description":"Event not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmation":{"type":"string"}},"required":["confirmation"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators":{"get":{"operationId":"EventsController.indexAdministrators","tags":["Events"],"description":"Get a list of all administrators for an event","responses":{"200":{"description":"A list of administrators for the event","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventAdministrator"}}}}},"403":{"description":"Missing permission to view administrators for this event"},"404":{"description":"Event not found"}},"security":[{"session":[]}]},"post":{"operationId":"EventsController.storeAdministrator","tags":["Events"],"description":"Create a new administrator for an event","responses":{"201":{"description":"The newly created administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event not found"},"409":{"description":"User is already an administrator of this event"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"number","minimum":0},"permissions":{"type":"number","minimum":0}},"required":["userId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{id}/administrators/{adminId}":{"put":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"EventsController.updateAdministrator","tags":["Events"],"description":"Update permissions for an event administrator","responses":{"200":{"description":"The updated administrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAdministrator"}}}},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"number","minimum":0}},"required":["permissions"],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"EventsController.destroyAdministrator","tags":["Events"],"description":"Remove administrator from an event","responses":{"204":{"description":"Administrator removed successfully"},"403":{"description":"Missing permission to manage administrators for this event"},"404":{"description":"Event or administrator not found"}},"security":[{"session":[]}]}},"/teams/{id}":{"get":{"operationId":"TeamsController.show","tags":["Teams"],"description":"Get a specific team by ID","responses":{"200":{"description":"The requested team","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Team"},{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}},"required":["members"]}]}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Team not found"}}},"put":{"operationId":"TeamsController.update","tags":["Teams"],"description":"Update a team by ID","responses":{"200":{"description":"The updated team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"403":{"description":"Missing permission to edit this team"},"404":{"description":"Team not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"TeamsController.update","tags":["Teams"],"description":"Update a team by ID","responses":{"200":{"description":"The updated team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"403":{"description":"Missing permission to edit this team"},"404":{"description":"Team not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"TeamsController.destroy","tags":["Teams"],"description":"Delete a team by ID. Requires confirmation of the team name.","responses":{"204":{"description":"Team deleted successfully"},"403":{"description":"Missing permission to delete this team"},"404":{"description":"Team not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmation":{"type":"string"}},"required":["confirmation"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{event_id}/teams":{"post":{"operationId":"TeamsController.store","tags":["Teams"],"description":"Create a new team in an event","responses":{"201":{"description":"The newly created team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"403":{"description":"Missing permission or invalid access code"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"accessCode":{"type":"string"}},"required":["name"],"additionalProperties":false}}}}},"get":{"operationId":"TeamsController.index","tags":["Teams"],"description":"Get a list of teams for an event","responses":{"200":{"description":"A list of teams","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/PaginationMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}},"required":["meta","data"]}}}},"403":{"description":"Missing permission to view this event"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":2}},{"name":"orderBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"orderDirection","in":"query","required":false,"schema":{"enum":["asc","desc"]}},{"name":"filter","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","pattern":"^[^:]+:[><=!~]{1,2}[^:]+$"},"description":"Custom filter in a format key:[op]value.\n        For example name:~Adam will find every name that contains Adam.\n        Supported ops: <, >, <=, >=, =, !, ~"}}]}},"/teams/{id}/invites":{"post":{"operationId":"TeamsController.storeInvite","tags":["Teams"],"description":"Create a new team invitation","responses":{"201":{"description":"The newly created invitation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamInvitation"}}}},"403":{"description":"Missing permission to invite to this team"},"404":{"description":"Team not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"validFor":{"enum":["1 hour","4 hours","12 hours","1 day","3 days","1 week"]}},"required":["validFor"],"additionalProperties":false}}}},"security":[{"session":[]}]},"get":{"operationId":"TeamsController.indexInvites","tags":["Teams"],"description":"Get a list of team invitations for a team","responses":{"200":{"description":"A list of team invitations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamInvitation"}}}}},"403":{"description":"Missing permission to edit this team"},"404":{"description":"Team not found"}},"security":[{"session":[]}]}},"/teams/{id}/kick":{"post":{"operationId":"TeamsController.kickMember","tags":["Teams"],"description":"Kick a member from a team","responses":{"204":{"description":"Team member removed successfully"},"403":{"description":"Missing permission to kick this member"},"404":{"description":"Team or member not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"member":{"type":"string","format":"uuid"}},"required":["member"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/invitations/{id}":{"get":{"operationId":"TeamsController.respondToInvite","tags":["Teams"],"description":"Accept or decline a team invitation","responses":{"200":{"description":"Invitation responded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"invitation":{"$ref":"#/components/schemas/TeamInvitation"},"member":{"$ref":"#/components/schemas/TeamMember"}},"required":["invitation","member"]}}}},"403":{"description":"Missing permission to respond to this invitation"},"404":{"description":"Invitation not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":16,"maxLength":45}},{"name":"action","in":"query","required":false,"schema":{"enum":["ACCEPT","REJECT"]}}],"security":[{"session":[]}]}},"/invitations":{"get":{"operationId":"TeamsController.indexUserInvites","tags":["Teams"],"description":"Get a list of pending team invitations for the current user","responses":{"200":{"description":"A list of team invitations for the user","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/PaginationMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TeamInvitation"}}},"required":["meta","data"]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":2}},{"name":"orderBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"orderDirection","in":"query","required":false,"schema":{"enum":["asc","desc"]}},{"name":"filter","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","pattern":"^[^:]+:[><=!~]{1,2}[^:]+$"},"description":"Custom filter in a format key:[op]value.\n        For example name:~Adam will find every name that contains Adam.\n        Supported ops: <, >, <=, >=, =, !, ~"}}],"security":[{"session":[]}]}},"/events/{event_id}/organizations":{"get":{"operationId":"OrganizationsController.index","tags":["Organizations"],"description":"Get a list of organizations for an event","responses":{"200":{"description":"A list of organizations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}}}}},"403":{"description":"Missing permission to view this event"}}},"post":{"operationId":"OrganizationsController.store","tags":["Organizations"],"description":"Create a new organization for an event","responses":{"201":{"description":"The newly created organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Missing permission to manage organizations"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string","maxLength":2000},"logoUrl":{"type":"string","format":"uri"},"websiteUrl":{"type":"string","format":"uri"}},"required":["name"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/events/{event_id}/organizations/{id}":{"get":{"operationId":"OrganizationsController.show","tags":["Organizations"],"description":"Get a specific organization by ID","responses":{"200":{"description":"The requested organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Organization not found"}}},"put":{"operationId":"OrganizationsController.update","tags":["Organizations"],"description":"Update an organization by ID","responses":{"200":{"description":"The updated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Missing permission to manage organizations"},"404":{"description":"Organization not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string","maxLength":2000},"logoUrl":{"type":"string","format":"uri"},"websiteUrl":{"type":"string","format":"uri"}},"required":["name"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"OrganizationsController.update","tags":["Organizations"],"description":"Update an organization by ID","responses":{"200":{"description":"The updated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Missing permission to manage organizations"},"404":{"description":"Organization not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string","maxLength":2000},"logoUrl":{"type":"string","format":"uri"},"websiteUrl":{"type":"string","format":"uri"}},"required":["name"],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroy","tags":["Organizations"],"description":"Delete an organization by ID","responses":{"204":{"description":"Organization deleted successfully"},"403":{"description":"Missing permission to manage organizations"},"404":{"description":"Organization not found"}},"security":[{"session":[]}]}},"/tasks/{id}/sponsors":{"get":{"operationId":"OrganizationsController.indexSponsors","tags":["Organizations"],"description":"Get a list of sponsors for a task","responses":{"200":{"description":"A list of sponsors for the task","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Sponsor"}}}}},"404":{"description":"Task not found"}},"security":[{"session":[]}]},"post":{"operationId":"OrganizationsController.storeSponsor","tags":["Organizations"],"description":"Create a new sponsor for a task","responses":{"201":{"description":"The newly created sponsor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sponsor"}}}},"400":{"description":"Organization does not belong to the same event"},"403":{"description":"Missing permission to manage sponsors"},"404":{"description":"Task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid"}},"required":["organizationId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/tasks/{id}/sponsors/{sponsorId}":{"get":{"operationId":"OrganizationsController.showSponsor","tags":["Organizations"],"description":"Get a specific sponsor by ID","responses":{"200":{"description":"The requested sponsor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sponsor"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Sponsor not found"}},"security":[{"session":[]}]},"delete":{"operationId":"OrganizationsController.destroySponsor","tags":["Organizations"],"description":"Delete a sponsor by ID","responses":{"204":{"description":"Sponsor deleted successfully"},"403":{"description":"Missing permission to manage sponsors"},"404":{"description":"Sponsor not found"}},"security":[{"session":[]}]}},"/tasks/{id}":{"get":{"operationId":"TasksController.show","tags":["Tasks"],"description":"Get a specific task by its ID or slug","responses":{"200":{"description":"The requested task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"403":{"description":"Missing permission to view this task"},"404":{"description":"Task not found"}}},"put":{"operationId":"TasksController.update","tags":["Tasks"],"description":"Update a task by its ID or slug","responses":{"200":{"description":"The updated task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"taskType":{"enum":["HACKATHON","CTF","ALGO"]},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"autoregister":{"type":"boolean"},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"resultsPublishedAt":{"type":"null"},"registrationStartAt":{"type":"null"},"registrationEndAt":{"type":"null"},"detailsRevealAt":{"type":"null"},"submissionsStartAt":{"type":"null"},"submissionsEndAt":{"type":"null"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"TasksController.update","tags":["Tasks"],"description":"Update a task by its ID or slug","responses":{"200":{"description":"The updated task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"taskType":{"enum":["HACKATHON","CTF","ALGO"]},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"autoregister":{"type":"boolean"},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"resultsPublishedAt":{"type":"null"},"registrationStartAt":{"type":"null"},"registrationEndAt":{"type":"null"},"detailsRevealAt":{"type":"null"},"submissionsStartAt":{"type":"null"},"submissionsEndAt":{"type":"null"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"TasksController.destroy","tags":["Tasks"],"description":"Delete a task by its ID or slug","responses":{"204":{"description":"Task deleted successfully"},"403":{"description":"Missing permission to delete this task"},"404":{"description":"Task not found"}},"security":[{"session":[]}]}},"/tasks/{taskId}/registrations":{"post":{"operationId":"TasksController.storeTaskRegistration","tags":["Tasks"],"description":"Register a team to a task","responses":{"201":{"description":"The newly created task registration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRegistration"}}}},"400":{"description":"Team does not belong to the same event or registration is not open"},"403":{"description":"Missing permission to register team"},"404":{"description":"Task or team not found"},"409":{"description":"Team is already registered to the task"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"teamId":{"type":"string","format":"uuid"}},"required":["teamId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/registrations/{id}":{"delete":{"operationId":"TasksController.destroyTaskRegistration","tags":["Tasks"],"description":"Unregister a team from a task","responses":{"204":{"description":"Task registration deleted successfully"},"403":{"description":"Missing permission to unregister team"},"404":{"description":"Task registration not found"}},"security":[{"session":[]}]}},"/hackathon/tasks/{id}":{"put":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"description":"Update a hackathon task by its ID or slug","responses":{"200":{"description":"The updated hackathon task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HackathonTask"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Hackathon task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requirementsDocumentUrl":{"type":"string","format":"uri"}},"required":["requirementsDocumentUrl"],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateTask","tags":["Hackathons"],"description":"Update a hackathon task by its ID or slug","responses":{"200":{"description":"The updated hackathon task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HackathonTask"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Hackathon task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requirementsDocumentUrl":{"type":"string","format":"uri"}},"required":["requirementsDocumentUrl"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury":{"get":{"operationId":"HackathonController.indexJuryMembers","tags":["Hackathons"],"description":"Get a list of jury members for a hackathon task","responses":{"200":{"description":"A list of jury members for the task","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JuryMember"}}}}},"404":{"description":"Task not found"}},"security":[{"session":[]}]},"post":{"operationId":"HackathonController.storeJuryMember","tags":["Hackathons"],"description":"Create a new jury member for a hackathon task","responses":{"201":{"description":"The newly created jury member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JuryMember"}}}},"400":{"description":"Invalid request or jury members can only be assigned to hackathon tasks"},"403":{"description":"Missing permission to manage jury members"},"404":{"description":"Task not found"},"409":{"description":"User is already a jury member"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"organizationId":{"type":["string","null"],"format":"uuid"},"userId":{"type":"number","minimum":0}},"required":["userId"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/hackathon/tasks/{id}/jury/{juryMemberId}":{"get":{"operationId":"HackathonController.showJuryMember","tags":["Hackathons"],"description":"Get a specific jury member by ID","responses":{"200":{"description":"The requested jury member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JuryMember"}}}},"403":{"description":"Missing permission to view this event"},"404":{"description":"Jury member not found"}},"security":[{"session":[]}]},"put":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"description":"Update a jury member by ID","responses":{"200":{"description":"The updated jury member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JuryMember"}}}},"403":{"description":"Missing permission to manage jury members"},"404":{"description":"Jury member not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"organizationId":{"type":["string","null"],"format":"uuid"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"HackathonController.updateJuryMember","tags":["Hackathons"],"description":"Update a jury member by ID","responses":{"200":{"description":"The updated jury member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JuryMember"}}}},"403":{"description":"Missing permission to manage jury members"},"404":{"description":"Jury member not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"organizationId":{"type":["string","null"],"format":"uuid"}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"HackathonController.destroyJuryMember","tags":["Hackathons"],"description":"Delete a jury member by ID","responses":{"204":{"description":"Jury member deleted successfully"},"403":{"description":"Missing permission to manage jury members"},"404":{"description":"Jury member not found"}},"security":[{"session":[]}]}},"/event/{event_id}/tasks":{"get":{"operationId":"TasksController.index","tags":["Tasks"],"description":"Get a list of tasks for an event","responses":{"200":{"description":"A list of tasks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}},"403":{"description":"Missing permission to view this event"}}}},"/event/{event_id}/task":{"post":{"operationId":"TasksController.store","tags":["Tasks"],"description":"Create a new task for an event","responses":{"201":{"description":"The newly created task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"403":{"description":"Missing permission to create tasks"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":255},"description":{"type":"string"},"taskType":{"enum":["HACKATHON","CTF","ALGO"]},"status":{"enum":["DRAFT","ACTIVE","ARCHIVED"]},"autoregister":{"enum":["1",1,"true",true,"on","0",0,"false",false]},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"resultsPublishedAt":{"type":"null"},"registrationStartAt":{"type":"null"},"registrationEndAt":{"type":"null"},"detailsRevealAt":{"type":"null"},"submissionsStartAt":{"type":"null"},"submissionsEndAt":{"type":"null"},"requirementsDocumentUrl":{"type":"string","format":"uri"}},"required":["title","description","taskType","slug"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/tasks/{task_id}/scores":{"get":{"operationId":"ScoresController.indexCriteria","tags":["Scores"],"description":"Get a list of scoring criteria for a task","responses":{"200":{"description":"A list of scoring criteria","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScoringCriterion"}}}}},"403":{"description":"Missing permission to view this task"},"404":{"description":"Task not found"}},"security":[{"session":[]}]},"post":{"operationId":"ScoresController.storeCriteria","tags":["Scores"],"description":"Create a new scoring criterion for a task","responses":{"201":{"description":"The newly created scoring criterion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringCriterion"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Task not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":255},"maximumScore":{"type":"integer","minimum":1},"weight":{"type":"number","minimum":0,"maximum":100},"description":{"type":["string","null"]}},"required":["category","maximumScore","weight"],"additionalProperties":false}}}},"security":[{"session":[]}]}},"/tasks/{task_id}/scores/{id}":{"get":{"operationId":"ScoresController.showCriteria","tags":["Scores"],"description":"Get a specific scoring criterion by ID","responses":{"200":{"description":"The requested scoring criterion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringCriterion"}}}},"403":{"description":"Missing permission to view this task"},"404":{"description":"Scoring criterion not found"}},"security":[{"session":[]}]},"put":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"description":"Update a scoring criterion by ID","responses":{"200":{"description":"The updated scoring criterion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringCriterion"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Scoring criterion not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":255},"maximumScore":{"type":"integer","minimum":1},"weight":{"type":"number","minimum":0,"maximum":100},"description":{"type":["string","null"]}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"patch":{"operationId":"ScoresController.updateCriteria","tags":["Scores"],"description":"Update a scoring criterion by ID","responses":{"200":{"description":"The updated scoring criterion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringCriterion"}}}},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Scoring criterion not found"}},"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":255},"maximumScore":{"type":"integer","minimum":1},"weight":{"type":"number","minimum":0,"maximum":100},"description":{"type":["string","null"]}},"required":[],"additionalProperties":false}}}},"security":[{"session":[]}]},"delete":{"operationId":"ScoresController.destroyCriteria","tags":["Scores"],"description":"Delete a scoring criterion by ID","responses":{"204":{"description":"Scoring criterion deleted successfully"},"403":{"description":"Missing permission to edit this task"},"404":{"description":"Scoring criterion not found"}},"security":[{"session":[]}]}}},"components":{"schemas":{"User":{"type":"object","properties":{"id":{"type":"number"},"nickname":{"example":"JohnnyBravo","type":"string"},"name":{"example":"John","type":"string"},"surname":{"example":"Bravo","type":"string"},"email":{"example":"johnny.bravo@example.com","type":"string"},"avatarUrl":{"example":"https://example.com/avatar.png","type":"string"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","nickname","email","permissions","createdAt","updatedAt"]},"Event":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"slug":{"example":"best-hackathon-ever","type":"string"},"title":{"example":"Awesome Hackathon","type":"string"},"description":{"example":"A first ever hackathon using a modern platform","type":"string"},"status":{"example":"ACTIVE","enum":["DRAFT","ACTIVE","ARCHIVED"]},"minTeamSize":{"type":"number"},"maxTeamSize":{"example":4,"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","title","description","status","minTeamSize","maxTeamSize","createdAt","updatedAt"]},"EventAdministrator":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08a","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"userId":{"type":"number"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","eventId","userId","permissions","createdAt","updatedAt"]},"Team":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"name":{"example":"Team Awesome","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","eventId","name","createdAt","updatedAt"]},"TeamMember":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"teamId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"userId":{"example":1,"type":"number"},"permissions":{"format":"binary","type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","teamId","userId","permissions","createdAt","updatedAt"]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"number"},"perPage":{"example":25,"type":"number"},"currentPage":{"type":"number"},"lastPage":{"example":3,"type":"number"},"firstPage":{"type":"number"},"firstPageUrl":{"example":"/data?page=1","type":"string"},"lastPageUrl":{"example":"/data?page=3","type":"string"},"nextPageUrl":{"example":"/data?page=2","type":"string"},"previousPageUrl":{"example":null,"type":"string"}},"required":["total","perPage","currentPage","lastPage","firstPage","firstPageUrl","lastPageUrl"]},"TeamInvitation":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"teamId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"inviterId":{"example":1,"type":"number"},"inviteeEmail":{"example":"user@example.com","type":"string"},"token":{"example":"secure-token-here","type":"string"},"status":{"example":"PENDING","enum":["PENDING","ACCEPTED","DECLINED","FAILED","EXPIRED"]},"expiresAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","teamId","inviterId","token","status","createdAt","updatedAt"]},"Organization":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"name":{"example":"Acme Corporation","type":"string"},"description":{"example":"A leading corporation","type":"string"},"logoUrl":{"example":"https://example.com/logo.png","type":"string"},"websiteUrl":{"example":"https://example.com","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","description","eventId","createdAt","updatedAt"]},"Sponsor":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"taskId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"organizationId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","taskId","organizationId","createdAt"]},"Task":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"eventId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"slug":{"example":"awesome-hackathon-task","type":"string"},"title":{"example":"Awesome Hackathon Task","type":"string"},"description":{"example":"Build an awesome application","type":"string"},"taskType":{"example":"HACKATHON","type":"string"},"status":{"example":"ACTIVE","type":"string"},"autoregister":{"example":false,"type":"boolean"},"resultsPublishedAt":{"format":"date-time","type":"string"},"registrationStartAt":{"format":"date-time","type":"string"},"registrationEndAt":{"format":"date-time","type":"string"},"detailsRevealAt":{"format":"date-time","type":"string"},"submissionsStartAt":{"format":"date-time","type":"string"},"submissionsEndAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","eventId","slug","title","description","taskType","status","autoregister","createdAt","updatedAt"]},"TaskRegistration":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"teamId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"taskId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","teamId","taskId","createdAt"]},"HackathonTask":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"taskId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"requirementsDocumentUrl":{"example":"https://example.com/requirements.pdf","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","taskId","requirementsDocumentUrl","createdAt","updatedAt"]},"JuryMember":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"description":{"example":"Senior judge with 10 years experience","type":"string"},"userId":{"example":1,"type":"number"},"taskId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"organizationId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","description","userId","taskId","createdAt","updatedAt"]},"ScoringCriterion":{"type":"object","properties":{"id":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"taskId":{"example":"d62a1715-6b7a-4b40-8bdd-4a10f2ceb08c","type":"string"},"category":{"example":"Code Quality","type":"string"},"description":{"example":"Assessment of code quality and best practices","type":"string"},"maximumScore":{"example":100,"type":"number"},"weight":{"example":1.5,"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","taskId","category","maximumScore","weight","createdAt","updatedAt"]}},"responses":{},"parameters":{},"examples":{},"requestBodies":{},"headers":{},"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"xcontest-session"}},"links":{},"callbacks":{}},"tags":[{"name":"Auth","description":"Endpoints provided by AuthController"},{"name":"Events","description":"Endpoints provided by EventsController"},{"name":"Teams","description":"Endpoints provided by TeamsController"},{"name":"Organizations","description":"Endpoints provided by OrganizationsController"},{"name":"Tasks","description":"Endpoints provided by TasksController"},{"name":"Hackathons","description":"Endpoints provided by HackathonsController"},{"name":"Scores","description":"Endpoints provided by ScoresController"}],"servers":[]}
\ No newline at end of file
diff --git a/docs/spec/spec.html b/docs/spec/spec.html
new file mode 100644
index 0000000..80fad0f
--- /dev/null
+++ b/docs/spec/spec.html
@@ -0,0 +1,24 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Scalar API Reference</title>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <!-- Load the Script -->
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+
+    <!-- Initialize the Scalar API Reference -->
+    <script type="text/javascript">
+      Scalar.createApiReference('#app', {
+        "url": "/spec/openapi.json",
+        "title": "xContest REST API",
+        "darkMode": true,
+        "theme": "purple"})
+    </script>
+  </body>
+</html>
\ No newline at end of file