feat: Support app-level tags and security apply to all app routes

aklinker1 · aklinker1 · commit 1de696eec536 · 2026-02-01T14:41:40.000-06:00
diff --git a/src/__tests__/app.test.ts b/src/__tests__/app.test.ts
@@ -1,11 +1,12 @@
-import { describe, it, expect, mock } from "bun:test";
-import { createApp } from "../app";
-import { z } from "zod/v4";
-import { createTestAppClient } from "../testing";
+import { describe, expect, it, mock } from "bun:test";
 import { expectTypeOf } from "expect-type";
-import type { AnyDef, GetAppData } from "../types";
+import type { OpenAPI } from "openapi-types";
+import { z } from "zod/v4";
 import { zodSchemaAdapter } from "../adapters/zod-schema-adapter";
+import { createApp } from "../app";
 import { HttpStatus } from "../status";
+import { createTestAppClient } from "../testing";
+import type { AnyDef, GetAppData } from "../types";
 
 // Silence console.error logs
 globalThis.console.error = mock();
@@ -448,4 +449,119 @@ describe("App", () => {
       expect(actual).toMatchObject({ a: "A" });
     });
   });
+
+  describe("app-level OpenAPI options", () => {
+    describe("tags", () => {
+      it("should apply app-level tags to all routes", () => {
+        const app = createApp({
+          schemaAdapter: zodSchemaAdapter,
+          tags: ["Users"],
+        })
+          .get("/", { responses: z.string() }, () => "")
+          .post("/", { responses: z.string() }, () => "");
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/"] as any).get.tags).toEqual(["Users"]);
+        expect((spec.paths!["/"] as any).post.tags).toEqual(["Users"]);
+      });
+
+      it("should allow route-level tags to override app-level tags", () => {
+        const app = createApp({
+          schemaAdapter: zodSchemaAdapter,
+          tags: ["Users"],
+        }).get("/", { tags: ["Admin"], responses: z.string() }, () => "");
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/"] as any).get.tags).toEqual(["Admin"]);
+      });
+
+      it("should preserve app-level tags when nested via use()", () => {
+        const usersApp = createApp({
+          prefix: "/users",
+          schemaAdapter: zodSchemaAdapter,
+          tags: ["Users"],
+        }).get("/", { responses: z.string() }, () => "");
+
+        const app = createApp({ schemaAdapter: zodSchemaAdapter }).use(
+          usersApp,
+        );
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/users"] as any).get.tags).toEqual(["Users"]);
+      });
+    });
+
+    describe("security", () => {
+      it("should apply app-level security to all routes", () => {
+        const app = createApp({
+          schemaAdapter: zodSchemaAdapter,
+          security: [{ bearerAuth: [] }],
+        })
+          .get("/", { responses: z.string() }, () => "")
+          .post("/", { responses: z.string() }, () => "");
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/"] as any).get.security).toEqual([
+          { bearerAuth: [] },
+        ]);
+        expect((spec.paths!["/"] as any).post.security).toEqual([
+          { bearerAuth: [] },
+        ]);
+      });
+
+      it("should allow route-level security to override app-level security", () => {
+        const app = createApp({
+          schemaAdapter: zodSchemaAdapter,
+          security: [{ bearerAuth: [] }],
+        }).get(
+          "/admin",
+          { security: [{ adminKey: [] }], responses: z.string() },
+          () => "",
+        );
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/admin"] as any).get.security).toEqual([
+          { adminKey: [] },
+        ]);
+      });
+
+      it("should preserve app-level security when nested via use()", () => {
+        const authApp = createApp({
+          prefix: "/auth",
+          schemaAdapter: zodSchemaAdapter,
+          security: [{ bearerAuth: [] }],
+        }).get("/profile", { responses: z.string() }, () => "");
+
+        const app = createApp({ schemaAdapter: zodSchemaAdapter }).use(authApp);
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/auth/profile"] as any).get.security).toEqual([
+          { bearerAuth: [] },
+        ]);
+      });
+    });
+
+    describe("tags and security combined", () => {
+      it("should apply both tags and security to routes", () => {
+        const app = createApp({
+          schemaAdapter: zodSchemaAdapter,
+          tags: ["Auth"],
+          security: [{ bearerAuth: [] }],
+        }).get("/profile", { responses: z.string() }, () => "");
+
+        const spec = app.getOpenApiSpec() as OpenAPI.Document;
+
+        expect((spec.paths!["/profile"] as any).get.tags).toEqual(["Auth"]);
+        expect((spec.paths!["/profile"] as any).get.security).toEqual([
+          { bearerAuth: [] },
+        ]);
+      });
+    });
+  });
 });
diff --git a/src/app.ts b/src/app.ts
@@ -1,4 +1,4 @@
-import type { OpenAPIV3_1 } from "openapi-types";
+import type { OpenAPI, OpenAPIV3_1 } from "openapi-types";
 import { addRoute, createRouter } from "rou3";
 import { compileRouter } from "rou3/compiler";
 import { compileFetchFunction } from "./internal/compile-fetch-function";
@@ -243,10 +243,15 @@ export function createApp<TPrefix extends BasePrefix = "">(
       app.method.apply(app, [Method.Any, ...args] as any) as any,
 
     method(method: string, path: BasePath, ...args: any[]) {
-      const def: RouteDef = args.length === 2 ? args[0] : undefined;
+      const routeDef: RouteDef | undefined =
+        args.length === 2 ? args[0] : undefined;
       const handler = args[1] ?? args[0];
       const route = `${prefix}${path}`;
       const hooks = cloneHooks();
+
+      // Merge app-level tags and security into route definition
+      const def: RouteDef | undefined = mergeAppDefaults(routeDef, options);
+
       const compiledHandler = compileRouteHandler({
         schemaAdapter: options?.schemaAdapter,
         def,
@@ -267,7 +272,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
 
     mount(...args: any[]) {
       let path = "";
-      let def = {};
+      let routeDef: RouteDef = {};
       let fetch: ServerSideFetch;
 
       if (args.length === 1) {
@@ -277,12 +282,16 @@ export function createApp<TPrefix extends BasePrefix = "">(
         fetch = args[1];
       } else {
         path = args[0];
-        def = args[1];
+        routeDef = args[1];
         fetch = args[2];
       }
 
       const route = `${prefix}${path}/**`;
       const hooks = cloneHooks();
+
+      // Merge app-level tags and security into route definition
+      const def = mergeAppDefaults(routeDef, options);
+
       const compiledHandler = compileRouteHandler({
         schemaAdapter: options?.schemaAdapter,
         hooks,
@@ -403,13 +412,64 @@ export type CreateAppOptions<TPrefix extends BasePrefix = ""> = {
 
   /** Configure how your application's OpenAPI docs are generated. */
   openApi?: Partial<OpenAPIV3_1.Document> & {};
+
+  /**
+   * OpenAPI tags to apply to all routes in this app. Route-level tags will
+   * override these app-level tags.
+   *
+   * @example
+   * ```ts
+   * const usersApp = createApp({
+   *   prefix: "/users",
+   *   tags: ["Users"],
+   * })
+   *   .get("/", {}, () => [...])  // Will have ["Users"] tag
+   *   .get("/:id", { tags: ["Admin"] }, () => {...})  // Will have ["Admin"] tag (overrides app-level)
+   * ```
+   */
+  tags?: string[];
+
+  /**
+   * OpenAPI security requirements to apply to all routes in this app.
+   * Route-level security will override these app-level security requirements.
+   *
+   * @example
+   * ```ts
+   * const authApp = createApp({
+   *   prefix: "/auth",
+   *   security: [{ bearerAuth: [] }],
+   * })
+   *   .get("/profile", {}, () => {...})  // Will require bearerAuth
+   *   .get("/admin", { security: [{ adminKey: [] }] }, () => {...})  // Will require adminKey (overrides app-level)
+   * ```
+   */
+  security?: OpenAPI.Document["security"];
   /**
    * Configure [Scalar](https://scalar.com/) UI docs.
    * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md#list-of-all-attributes
    */
   scalar?: any;
 };
 
+/**
+ * Apply app-level defaults (tags, security) to a route definition.
+ * Route-level values override app-level defaults.
+ */
+function mergeAppDefaults(
+  routeDef: RouteDef | undefined,
+  options: CreateAppOptions<any> | undefined,
+): RouteDef | undefined {
+  if (!options?.tags?.length && !options?.security?.length) {
+    return routeDef;
+  }
+
+  return {
+    tags: options.tags,
+    security: options.security,
+    ...routeDef,
+  };
+}
+
 enum Method {
   Get = "GET",
   Post = "POST",
