feat(apis): ROSS-212: add tags field to api config for swagger schema

example_config.json

@@ -220,6 +220,7 @@
                 }
             ],
             "authorization": true,
+            "tags": ["Users", "Aggregations"],
             "serverParams": [
                 {
                     "type": "query",

src/interfaces/config.ts

@@ -203,6 +203,7 @@ export interface ServerParamConfig {
 export interface ApisConfig {
   [key: string]: {
     enabled?: boolean;
+    tags?: string[];
     webhooks?: WebhookConfig[];
     serverParams?: ServerParamConfig[];
     authorization?: boolean;

src/routes/aggregate/aggregate.ts

@@ -39,6 +39,7 @@ export function registerAggregateRoutes(
           config.apis?.[defaultApiIdentifier]?.authorization ??
           config.authentication?.enabled ??
           false;
+        const defaultTags = config.apis?.[defaultApiIdentifier]?.tags;
 
         registerAggregateEndpoint(
           app,
@@ -49,6 +50,7 @@ export function registerAggregateRoutes(
           defaultVariant,
           defaultApiIdentifier,
           defaultAuthorization,
+          defaultTags,
         );
       }
 
@@ -78,6 +80,8 @@ export function registerAggregateRoutes(
           config.authentication?.enabled ??
           false;
 
+        const variantTags = config.apis?.[variantApiIdentifier]?.tags;
+
         registerAggregateEndpoint(
           app,
           config,
@@ -87,6 +91,7 @@ export function registerAggregateRoutes(
           variant,
           variantApiIdentifier,
           variantAuthorization,
+          variantTags,
         );
       }
     }
@@ -105,6 +110,7 @@ function registerAggregateEndpoint(
   variant: string,
   apiIdentifier: string,
   authorization: boolean,
+  routeTags?: string[],
 ): void {
   // Build path with variant prefix
   const path = `/${variant}/${modelName}/aggregation/${fieldName}`;
@@ -115,6 +121,7 @@ function registerAggregateEndpoint(
     modelName,
     aggregations,
     authorization,
+    routeTags,
   );
 
   app.get(
@@ -233,13 +240,14 @@ function generateSchema(
   modelName: string,
   aggregations: Aggregation[],
   authorization: boolean,
+  routeTags?: string[],
 ) {
   const security = buildSecurityArray(config, authorization);
 
   const schema: Record<string, unknown> = {
     summary: `Aggregate ${fieldName} on ${capitalizeFirstLetter(modelName)}`,
     description: `Get aggregation data for ${fieldName} in ${modelName}`,
-    tags: [capitalizeFirstLetter(modelName), 'Read'],
+    tags: routeTags ?? [capitalizeFirstLetter(modelName), 'Read'],
     querystring: {
       type: 'object',
       properties: {

src/routes/auth/change-email.ts

@@ -34,6 +34,8 @@ export function registerEmailChangeRoute(
 
   if (config.apis?.[defaultApiIdentifier]?.enabled === false) return;
 
+  const defaultTags = config.apis?.[defaultApiIdentifier]?.tags;
+
   registerEmailChangeEndpoint(
     app,
     config,
@@ -43,6 +45,7 @@ export function registerEmailChangeRoute(
     isVerifiedField,
     defaultVariant,
     defaultApiIdentifier,
+    defaultTags,
   );
 
   const baseIdentifier = buildApiIdentifier(
@@ -65,6 +68,8 @@ export function registerEmailChangeRoute(
 
     if (config.apis?.[variantApiIdentifier]?.enabled === false) continue;
 
+    const variantTags = config.apis?.[variantApiIdentifier]?.tags;
+
     registerEmailChangeEndpoint(
       app,
       config,
@@ -74,6 +79,7 @@ export function registerEmailChangeRoute(
       isVerifiedField,
       variant,
       variantApiIdentifier,
+      variantTags,
     );
   }
 }
@@ -87,8 +93,13 @@ function registerEmailChangeEndpoint(
   isVerifiedField: string | undefined,
   variant: string,
   apiIdentifier: string,
+  routeTags?: string[],
 ): void {
-  const schema: Record<string, unknown> = generateSchema(usernameField, model);
+  const schema: Record<string, unknown> = generateSchema(
+    usernameField,
+    model,
+    routeTags,
+  );
 
   const path = `/${variant}/auth/user/email`;
 
@@ -169,7 +180,11 @@ function registerEmailChangeEndpoint(
   );
 }
 
-function generateSchema(usernameField: string, model: string) {
+function generateSchema(
+  usernameField: string,
+  model: string,
+  routeTags?: string[],
+) {
   const bodySchema = {
     type: 'object',
     required: [usernameField],
@@ -195,7 +210,7 @@ function generateSchema(usernameField: string, model: string) {
   const schema: Record<string, unknown> = {
     summary: `Change email for ${capitalizeFirstLetter(model)}`,
     description: `Updates the email address for the authenticated user in the "${model}" table and sends an OTP to the new email.`,
-    tags: [capitalizeFirstLetter(model), 'Auth', 'Profile'],
+    tags: routeTags ?? [capitalizeFirstLetter(model), 'Auth', 'Profile'],
     body: bodySchema,
     response: responseSchema,
     security: [{bearerAuth: []}],

src/routes/auth/change-password.ts

@@ -35,6 +35,8 @@ export function registerChangePasswordRoute(
 
   if (config.apis?.[defaultApiIdentifier]?.enabled === false) return;
 
+  const defaultTags = config.apis?.[defaultApiIdentifier]?.tags;
+
   registerChangePasswordEndpoint(
     app,
     config,
@@ -43,6 +45,7 @@ export function registerChangePasswordRoute(
     passwordField,
     defaultVariant,
     defaultApiIdentifier,
+    defaultTags,
   );
 
   const baseIdentifier = buildApiIdentifier(
@@ -65,6 +68,8 @@ export function registerChangePasswordRoute(
 
     if (config.apis?.[variantApiIdentifier]?.enabled === false) continue;
 
+    const variantTags = config.apis?.[variantApiIdentifier]?.tags;
+
     registerChangePasswordEndpoint(
       app,
       config,
@@ -73,6 +78,7 @@ export function registerChangePasswordRoute(
       passwordField,
       variant,
       variantApiIdentifier,
+      variantTags,
     );
   }
 }
@@ -85,8 +91,9 @@ function registerChangePasswordEndpoint(
   passwordField: string,
   variant: string,
   apiIdentifier: string,
+  routeTags?: string[],
 ): void {
-  const schema: Record<string, unknown> = generateSchema(model);
+  const schema: Record<string, unknown> = generateSchema(model, routeTags);
 
   const path = `/${variant}/auth/change-password`;
 
@@ -165,7 +172,7 @@ function registerChangePasswordEndpoint(
   );
 }
 
-function generateSchema(model: string) {
+function generateSchema(model: string, routeTags?: string[]) {
   const bodySchema = {
     type: 'object',
     required: ['existingPassword', 'newPassword'],
@@ -192,7 +199,7 @@ function generateSchema(model: string) {
   const schema: Record<string, unknown> = {
     summary: `Change password for ${capitalizeFirstLetter(model)}`,
     description: `Changes the password for an authenticated user in the "${model}" table.`,
-    tags: [capitalizeFirstLetter(model), 'Auth', 'Password'],
+    tags: routeTags ?? [capitalizeFirstLetter(model), 'Auth', 'Password'],
     body: bodySchema,
     response: responseSchema,
     security: [{bearerAuth: []}],

src/routes/auth/delete-me.ts

@@ -34,13 +34,16 @@ export function registerDeleteMeRoute(
 
   if (config.apis?.[defaultApiIdentifier]?.enabled === false) return;
 
+  const defaultTags = config.apis?.[defaultApiIdentifier]?.tags;
+
   registerDeleteMeEndpoint(
     app,
     config,
     model,
     idField,
     defaultVariant,
     defaultApiIdentifier,
+    defaultTags,
   );
 
   const baseIdentifier = buildApiIdentifier(
@@ -63,13 +66,16 @@ export function registerDeleteMeRoute(
 
     if (config.apis?.[variantApiIdentifier]?.enabled === false) continue;
 
+    const variantTags = config.apis?.[variantApiIdentifier]?.tags;
+
     registerDeleteMeEndpoint(
       app,
       config,
       model,
       idField,
       variant,
       variantApiIdentifier,
+      variantTags,
     );
   }
 }
@@ -81,8 +87,9 @@ function registerDeleteMeEndpoint(
   idField: string,
   variant: string,
   apiIdentifier: string,
+  routeTags?: string[],
 ): void {
-  const schema: Record<string, unknown> = generateSchema(model);
+  const schema: Record<string, unknown> = generateSchema(model, routeTags);
 
   const path = `/${variant}/auth/user/me`;
 
@@ -140,7 +147,7 @@ function registerDeleteMeEndpoint(
   );
 }
 
-function generateSchema(model: string) {
+function generateSchema(model: string, routeTags?: string[]) {
   const responseSchema = getResponseStructureSchema([200], {
     type: 'object',
     properties: {
@@ -151,7 +158,7 @@ function generateSchema(model: string) {
   const schema: Record<string, unknown> = {
     summary: `Delete authenticated user profile for ${capitalizeFirstLetter(model)}`,
     description: `Permanently deletes the currently authenticated user from the "${model}" table.`,
-    tags: [capitalizeFirstLetter(model), 'Auth', 'Profile'],
+    tags: routeTags ?? [capitalizeFirstLetter(model), 'Auth', 'Profile'],
     response: responseSchema,
     security: [{bearerAuth: []}],
   };

src/routes/auth/edit-me.ts

@@ -42,6 +42,8 @@ export function registerEditMeRoute(
 
   if (config.apis?.[defaultApiIdentifier]?.enabled === false) return;
 
+  const defaultTags = config.apis?.[defaultApiIdentifier]?.tags;
+
   registerEditMeEndpoint(
     app,
     config,
@@ -53,6 +55,7 @@ export function registerEditMeRoute(
     isVerifiedField,
     defaultVariant,
     defaultApiIdentifier,
+    defaultTags,
   );
 
   const baseIdentifier = buildApiIdentifier(
@@ -75,6 +78,8 @@ export function registerEditMeRoute(
 
     if (config.apis?.[variantApiIdentifier]?.enabled === false) continue;
 
+    const variantTags = config.apis?.[variantApiIdentifier]?.tags;
+
     registerEditMeEndpoint(
       app,
       config,
@@ -86,6 +91,7 @@ export function registerEditMeRoute(
       isVerifiedField,
       variant,
       variantApiIdentifier,
+      variantTags,
     );
   }
 }
@@ -101,6 +107,7 @@ function registerEditMeEndpoint(
   isVerifiedField: string | undefined,
   variant: string,
   apiIdentifier: string,
+  routeTags?: string[],
 ): void {
   const schema: Record<string, unknown> = generateSchema(
     authModelConfig,
@@ -109,6 +116,7 @@ function registerEditMeEndpoint(
     usernameField,
     passwordField,
     isVerifiedField,
+    routeTags,
   );
 
   const path = `/${variant}/auth/user/me`;
@@ -210,6 +218,7 @@ function generateSchema(
   usernameField: string,
   passwordField: string,
   isVerifiedField?: string,
+  routeTags?: string[],
 ) {
   const protectedFields = new Set(
     [idField, usernameField, passwordField, isVerifiedField].filter(Boolean),
@@ -239,7 +248,7 @@ function generateSchema(
   const schema: Record<string, unknown> = {
     summary: `Edit authenticated user profile for ${capitalizeFirstLetter(model)}`,
     description: `Updates the profile of the currently authenticated user in the "${model}" table. Cannot update ${idField}, ${usernameField}, ${passwordField}, or ${isVerifiedField}.`,
-    tags: [capitalizeFirstLetter(model), 'Auth', 'Profile'],
+    tags: routeTags ?? [capitalizeFirstLetter(model), 'Auth', 'Profile'],
     body: bodySchema,
     response: responseSchema,
     security: [{bearerAuth: []}],