feat(categories): category CRUD with pagination, caching and Swagger docs

.adonisjs/client/registry/index.ts

@@ -162,6 +162,36 @@ const routes = {
     tokens: [{"old":"/api/v1/permissions/:id","type":0,"val":"api","end":""},{"old":"/api/v1/permissions/:id","type":0,"val":"v1","end":""},{"old":"/api/v1/permissions/:id","type":0,"val":"permissions","end":""},{"old":"/api/v1/permissions/:id","type":1,"val":"id","end":""}],
     types: placeholder as Registry['permissions.destroy']['types'],
   },
+  'categories.index': {
+    methods: ["GET","HEAD"],
+    pattern: '/api/v1/categories',
+    tokens: [{"old":"/api/v1/categories","type":0,"val":"api","end":""},{"old":"/api/v1/categories","type":0,"val":"v1","end":""},{"old":"/api/v1/categories","type":0,"val":"categories","end":""}],
+    types: placeholder as Registry['categories.index']['types'],
+  },
+  'categories.show': {
+    methods: ["GET","HEAD"],
+    pattern: '/api/v1/categories/:id',
+    tokens: [{"old":"/api/v1/categories/:id","type":0,"val":"api","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"v1","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"categories","end":""},{"old":"/api/v1/categories/:id","type":1,"val":"id","end":""}],
+    types: placeholder as Registry['categories.show']['types'],
+  },
+  'categories.store': {
+    methods: ["POST"],
+    pattern: '/api/v1/categories',
+    tokens: [{"old":"/api/v1/categories","type":0,"val":"api","end":""},{"old":"/api/v1/categories","type":0,"val":"v1","end":""},{"old":"/api/v1/categories","type":0,"val":"categories","end":""}],
+    types: placeholder as Registry['categories.store']['types'],
+  },
+  'categories.update': {
+    methods: ["PUT"],
+    pattern: '/api/v1/categories/:id',
+    tokens: [{"old":"/api/v1/categories/:id","type":0,"val":"api","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"v1","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"categories","end":""},{"old":"/api/v1/categories/:id","type":1,"val":"id","end":""}],
+    types: placeholder as Registry['categories.update']['types'],
+  },
+  'categories.destroy': {
+    methods: ["DELETE"],
+    pattern: '/api/v1/categories/:id',
+    tokens: [{"old":"/api/v1/categories/:id","type":0,"val":"api","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"v1","end":""},{"old":"/api/v1/categories/:id","type":0,"val":"categories","end":""},{"old":"/api/v1/categories/:id","type":1,"val":"id","end":""}],
+    types: placeholder as Registry['categories.destroy']['types'],
+  },
 } as const satisfies Record<string, AdonisEndpoint>
 
 export { routes }

.adonisjs/client/registry/schema.d.ts

@@ -122,9 +122,9 @@ export interface Registry {
       body: {}
       paramsTuple: []
       params: {}
-      query: {}
+      query: ExtractQueryForGet<InferInput<(typeof import('#validators/pagination_validator').paginationSchema)>>
       response: ExtractResponse<Awaited<ReturnType<import('#controllers/users_controller').default['index']>>>
-      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/users_controller').default['index']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/users_controller').default['index']>>> | { status: 422; response: { errors: SimpleError[] } }
     }
   }
   'users.show': {
@@ -194,9 +194,9 @@ export interface Registry {
       body: {}
       paramsTuple: []
       params: {}
-      query: {}
+      query: ExtractQueryForGet<InferInput<(typeof import('#validators/pagination_validator').paginationSchema)>>
       response: ExtractResponse<Awaited<ReturnType<import('#controllers/roles_controller').default['index']>>>
-      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/roles_controller').default['index']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/roles_controller').default['index']>>> | { status: 422; response: { errors: SimpleError[] } }
     }
   }
   'roles.show': {
@@ -278,9 +278,9 @@ export interface Registry {
       body: {}
       paramsTuple: []
       params: {}
-      query: {}
+      query: ExtractQueryForGet<InferInput<(typeof import('#validators/pagination_validator').paginationSchema)>>
       response: ExtractResponse<Awaited<ReturnType<import('#controllers/permissions_controller').default['index']>>>
-      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/permissions_controller').default['index']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/permissions_controller').default['index']>>> | { status: 422; response: { errors: SimpleError[] } }
     }
   }
   'permissions.store': {
@@ -319,4 +319,64 @@ export interface Registry {
       errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/permissions_controller').default['destroy']>>>
     }
   }
+  'categories.index': {
+    methods: ["GET","HEAD"]
+    pattern: '/api/v1/categories'
+    types: {
+      body: {}
+      paramsTuple: []
+      params: {}
+      query: ExtractQueryForGet<InferInput<(typeof import('#validators/pagination_validator').paginationSchema)>>
+      response: ExtractResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['index']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['index']>>> | { status: 422; response: { errors: SimpleError[] } }
+    }
+  }
+  'categories.show': {
+    methods: ["GET","HEAD"]
+    pattern: '/api/v1/categories/:id'
+    types: {
+      body: {}
+      paramsTuple: [ParamValue]
+      params: { id: ParamValue }
+      query: {}
+      response: ExtractResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['show']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['show']>>>
+    }
+  }
+  'categories.store': {
+    methods: ["POST"]
+    pattern: '/api/v1/categories'
+    types: {
+      body: ExtractBody<InferInput<(typeof import('#validators/category_validator').createCategorySchema)>>
+      paramsTuple: []
+      params: {}
+      query: ExtractQuery<InferInput<(typeof import('#validators/category_validator').createCategorySchema)>>
+      response: ExtractResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['store']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['store']>>> | { status: 422; response: { errors: SimpleError[] } }
+    }
+  }
+  'categories.update': {
+    methods: ["PUT"]
+    pattern: '/api/v1/categories/:id'
+    types: {
+      body: ExtractBody<InferInput<(typeof import('#validators/category_validator').updateCategorySchema)>>
+      paramsTuple: [ParamValue]
+      params: { id: ParamValue }
+      query: ExtractQuery<InferInput<(typeof import('#validators/category_validator').updateCategorySchema)>>
+      response: ExtractResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['update']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['update']>>> | { status: 422; response: { errors: SimpleError[] } }
+    }
+  }
+  'categories.destroy': {
+    methods: ["DELETE"]
+    pattern: '/api/v1/categories/:id'
+    types: {
+      body: {}
+      paramsTuple: [ParamValue]
+      params: { id: ParamValue }
+      query: {}
+      response: ExtractResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['destroy']>>>
+      errorResponse: ExtractErrorResponse<Awaited<ReturnType<import('#controllers/categories_controller').default['destroy']>>>
+    }
+  }
 }

.adonisjs/client/registry/tree.d.ts

@@ -38,4 +38,11 @@ export interface ApiDefinition {
     update: typeof routes['permissions.update']
     destroy: typeof routes['permissions.destroy']
   }
+  categories: {
+    index: typeof routes['categories.index']
+    show: typeof routes['categories.show']
+    store: typeof routes['categories.store']
+    update: typeof routes['categories.update']
+    destroy: typeof routes['categories.destroy']
+  }
 }

.adonisjs/server/controllers.ts

@@ -5,6 +5,7 @@
 
 export const controllers = {
   Auth: () => import('#controllers/auth_controller'),
+  Categories: () => import('#controllers/categories_controller'),
   Health: () => import('#controllers/health_controller'),
   Permissions: () => import('#controllers/permissions_controller'),
   Roles: () => import('#controllers/roles_controller'),

.adonisjs/server/routes.d.ts

@@ -30,6 +30,11 @@ export type ScannedRoutes = {
     'permissions.store': { paramsTuple?: []; params?: {} }
     'permissions.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'permissions.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
+    'categories.index': { paramsTuple?: []; params?: {} }
+    'categories.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
+    'categories.store': { paramsTuple?: []; params?: {} }
+    'categories.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
+    'categories.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
   }
   GET: {
     'health.index': { paramsTuple?: []; params?: {} }
@@ -39,6 +44,8 @@ export type ScannedRoutes = {
     'roles.index': { paramsTuple?: []; params?: {} }
     'roles.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'permissions.index': { paramsTuple?: []; params?: {} }
+    'categories.index': { paramsTuple?: []; params?: {} }
+    'categories.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
   }
   HEAD: {
     'health.index': { paramsTuple?: []; params?: {} }
@@ -48,6 +55,8 @@ export type ScannedRoutes = {
     'roles.index': { paramsTuple?: []; params?: {} }
     'roles.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'permissions.index': { paramsTuple?: []; params?: {} }
+    'categories.index': { paramsTuple?: []; params?: {} }
+    'categories.show': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
   }
   POST: {
     'auth.register': { paramsTuple?: []; params?: {} }
@@ -61,18 +70,21 @@ export type ScannedRoutes = {
     'roles.store': { paramsTuple?: []; params?: {} }
     'roles.assign_permission': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'permissions.store': { paramsTuple?: []; params?: {} }
+    'categories.store': { paramsTuple?: []; params?: {} }
   }
   PUT: {
     'users.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'roles.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'permissions.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
+    'categories.update': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
   }
   DELETE: {
     'users.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'users.revoke_role': { paramsTuple: [ParamValue,ParamValue]; params: {'id': ParamValue,'roleId': ParamValue} }
     'roles.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
     'roles.revoke_permission': { paramsTuple: [ParamValue,ParamValue]; params: {'id': ParamValue,'permissionId': ParamValue} }
     'permissions.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
+    'categories.destroy': { paramsTuple: [ParamValue]; params: {'id': ParamValue} }
   }
 }
 declare module '@adonisjs/core/types/http' {

app/controllers/categories_controller.ts

@@ -0,0 +1,94 @@
+import { inject } from '@adonisjs/core'
+import type { HttpContext } from '@adonisjs/core/http'
+
+import { respond } from '#helpers/api_response'
+import CategoriesService from '#services/categories_service'
+import { createCategorySchema, updateCategorySchema } from '#validators/category_validator'
+import { paginationSchema } from '#validators/pagination_validator'
+
+/**
+ * Thin HTTP layer over CategoriesService. GET routes are public; the
+ * mutation routes (store, update, destroy) are declared behind
+ * `middleware.auth()` + `middleware.role({ roles: ['ADMIN'] })` in
+ * start/routes.ts, the same pattern RolesController and
+ * PermissionsController already use for their own mutation routes.
+ */
+@inject()
+export default class CategoriesController {
+  constructor(private categoriesService: CategoriesService) {}
+
+  /**
+   * @index
+   * @summary List categories
+   * @description Returns a paginated list of categories. Public endpoint, cached by page and limit.
+   * @paramQuery page - Page number - @type(number)
+   * @paramQuery limit - Items per page, capped at 100 - @type(number)
+   * @responseBody 200 - <Category[]>.paginated()
+   */
+  async index({ request, response }: HttpContext) {
+    const { page, limit } = await request.validateUsing(paginationSchema)
+    const result = await this.categoriesService.findAll(page ?? 1, limit ?? 10)
+    return response.ok(respond(result))
+  }
+
+  /**
+   * @show
+   * @summary Get a category
+   * @description Returns a single category by id. Public endpoint.
+   * @paramPath id - The category id - @type(number) @required
+   * @responseBody 200 - <Category>
+   * @responseBody 404 - Category not found
+   */
+  async show({ params, response }: HttpContext) {
+    const category = await this.categoriesService.findOne(Number(params.id))
+    return response.ok(respond(category, 'Category detail'))
+  }
+
+  /**
+   * @store
+   * @summary Create a category
+   * @description Creates a new category. ADMIN only.
+   * @requestBody <createCategorySchema>
+   * @responseBody 201 - <Category>
+   * @responseBody 401 - Missing or invalid token
+   * @responseBody 403 - Caller is not an ADMIN
+   */
+  async store({ request, response }: HttpContext) {
+    const data = await request.validateUsing(createCategorySchema)
+    const category = await this.categoriesService.create(data)
+    return response.created(respond(category, 'Category created'))
+  }
+
+  /**
+   * @update
+   * @summary Update a category
+   * @description Partially updates an existing category. ADMIN only.
+   * @paramPath id - The category id - @type(number) @required
+   * @requestBody <updateCategorySchema>
+   * @responseBody 200 - <Category>
+   * @responseBody 401 - Missing or invalid token
+   * @responseBody 403 - Caller is not an ADMIN
+   * @responseBody 404 - Category not found
+   */
+  async update({ params, request, response }: HttpContext) {
+    const data = await request.validateUsing(updateCategorySchema)
+    const category = await this.categoriesService.update(Number(params.id), data)
+    return response.ok(respond(category, 'Category updated'))
+  }
+
+  /**
+   * @destroy
+   * @summary Delete a category
+   * @description Deletes a category. ADMIN only. Fails with 409 when the category still has products associated with it.
+   * @paramPath id - The category id - @type(number) @required
+   * @responseBody 200 - Category deleted
+   * @responseBody 401 - Missing or invalid token
+   * @responseBody 403 - Caller is not an ADMIN
+   * @responseBody 404 - Category not found
+   * @responseBody 409 - Category still has products associated with it
+   */
+  async destroy({ params, response }: HttpContext) {
+    await this.categoriesService.remove(Number(params.id))
+    return response.ok(respond(null, 'Category deleted'))
+  }
+}