Complete examples/tags implementation with registerRouteHandlersByTag

- Added tags to operations in openapi.yaml (pets, media tags, plus untagged mixedContentTypes)
- Updated api.ts to create service implementations per tag (petsService, mediaService, untaggedService)
- Updated app.ts to use registerRouteHandlersByTag to mount each service to /api
- Updated app.test.ts to test all routes including newly implemented listPets

Co-authored-by: jasonblanchard <1238532+jasonblanchard@users.noreply.github.com>

Author: Copilot

examples/tags/api.ts

@@ -1,5 +1,4 @@
 import type * as ServerTypes from "./gen/server.ts";
-import * as server from "./gen/server.ts";
 import type { Request, Response } from "express";
 import { promises as fs } from "fs";
 import { join } from "path";
@@ -8,8 +7,24 @@ import { fileURLToPath } from "url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = join(__filename, "..");
 
-const API: ServerTypes.Server<Request, Response> = {
-  getPetById: async ({ parameters, req }): ServerTypes.GetPetByIdResult => {
+// Service implementation for "pets" tag
+export const petsService: ServerTypes.ServerForPets<Request, Response> = {
+  listPets: async (): ServerTypes.ListPetsResult => {
+    return {
+      content: {
+        200: {
+          "application/json": {
+            pets: [
+              { id: 1, name: "dog" },
+              { id: 2, name: "cat" },
+            ],
+          },
+        },
+      },
+    };
+  },
+
+  getPetById: async ({ parameters }): ServerTypes.GetPetByIdResult => {
     if (parameters.path.petId === 42) {
       return {
         content: {
@@ -56,45 +71,10 @@ const API: ServerTypes.Server<Request, Response> = {
       },
     };
   },
+};
 
-  mixedContentTypes: async ({
-    parameters,
-    requestBody,
-    contentType,
-  }): ServerTypes.MixedContentTypesResult => {
-    const { petId } = parameters.path;
-    let status: "available" | "pending" | "sold" | undefined;
-
-    // Since each content type has different structures,
-    // use the request content type and requestBody discriminator to narrow the type in each case.
-
-    if (
-      contentType === "application/json" &&
-      requestBody.mediaType === "application/json"
-    ) {
-      status = requestBody.content.jsonstatus;
-    }
-
-    if (
-      contentType == "application/xml" &&
-      requestBody.mediaType === "application/xml"
-    ) {
-      status = requestBody.content.xmlstatus;
-    }
-
-    return {
-      content: {
-        200: {
-          "application/json": {
-            pet: { id: petId, name: "dog", status },
-          },
-        },
-      },
-    };
-  },
-
-  listPets: server.listPetsUnimplemented,
-
+// Service implementation for "media" tag
+export const mediaService: ServerTypes.ServerForMedia<Request, Response> = {
   getPetImage: async (): ServerTypes.GetPetImageResult => {
     const image = await fs.readFile(join(__dirname, `./cat.jpeg`), {
       encoding: "base64",
@@ -121,4 +101,42 @@ const API: ServerTypes.Server<Request, Response> = {
   },
 };
 
-export default API;
+// Service implementation for untagged operations
+export const untaggedService: ServerTypes.ServerForUntagged<Request, Response> =
+  {
+    mixedContentTypes: async ({
+      parameters,
+      requestBody,
+      contentType,
+    }): ServerTypes.MixedContentTypesResult => {
+      const { petId } = parameters.path;
+      let status: "available" | "pending" | "sold" | undefined;
+
+      // Since each content type has different structures,
+      // use the request content type and requestBody discriminator to narrow the type in each case.
+
+      if (
+        contentType === "application/json" &&
+        requestBody.mediaType === "application/json"
+      ) {
+        status = requestBody.content.jsonstatus;
+      }
+
+      if (
+        contentType == "application/xml" &&
+        requestBody.mediaType === "application/xml"
+      ) {
+        status = requestBody.content.xmlstatus;
+      }
+
+      return {
+        content: {
+          200: {
+            "application/json": {
+              pet: { id: petId, name: "dog", status },
+            },
+          },
+        },
+      };
+    },
+  };

examples/tags/app.test.ts

@@ -129,38 +129,43 @@ describe("mixed content types with different structures", async () => {
 });
 
 describe("listPets", async () => {
-  it("propagates unimplemented error", async () => {
+  it("returns 200", async () => {
     const response = await request(app)
       .get("/api/v3/pets")
       .set("Accept", "application/json");
 
-    assert.equal(response.status, 501);
-    assert.equal(response.body.message, "Not Implemented");
+    assert.equal(response.status, 200);
+    assert.deepEqual(response.body, {
+      pets: [
+        { id: 1, name: "dog" },
+        { id: 2, name: "cat" },
+      ],
+    });
   });
+});
 
-  describe("getPetImage", async () => {
-    it("returns 200", async () => {
-      const response = await request(app)
-        .get("/api/v3/pet/123/image")
-        .set("Accept", "image/jpeg");
+describe("getPetImage", async () => {
+  it("returns 200", async () => {
+    const response = await request(app)
+      .get("/api/v3/pet/123/image")
+      .set("Accept", "image/jpeg");
 
-      assert.equal(response.status, 200);
-      assert(response.body);
-      assert.equal(response.headers["content-type"], "image/jpeg");
-    });
+    assert.equal(response.status, 200);
+    assert(response.body);
+    assert.equal(response.headers["content-type"], "image/jpeg");
   });
+});
 
-  describe("getPetWebpage", async () => {
-    it("returns 200", async () => {
-      const response = await request(app)
-        .get("/api/v3/pet/123/webpage")
-        .set("Accept", "text/html");
-
-      assert.equal(response.status, 200);
-      assert.equal(
-        response.text,
-        "<html><body><h1>Hello, pet 123!</h1></body></html>",
-      );
-    });
+describe("getPetWebpage", async () => {
+  it("returns 200", async () => {
+    const response = await request(app)
+      .get("/api/v3/pet/123/webpage")
+      .set("Accept", "text/html");
+
+    assert.equal(response.status, 200);
+    assert.equal(
+      response.text,
+      "<html><body><h1>Hello, pet 123!</h1></body></html>",
+    );
   });
 });

examples/tags/app.ts

@@ -1,8 +1,8 @@
 import express from "express";
 import type { Request, Response, NextFunction } from "express";
-import { registerRouteHandlers } from "./gen/server.ts";
+import { registerRouteHandlersByTag } from "./gen/server.ts";
 import registerRoutes from "openapi-typescript-server-express";
-import API from "./api.ts";
+import { petsService, mediaService, untaggedService } from "./api.ts";
 import OpenApiValidator from "express-openapi-validator";
 import { NotImplementedError } from "openapi-typescript-server-runtime";
 import xmlparser from "express-xml-bodyparser";
@@ -26,13 +26,23 @@ export default function makeApp() {
       validateResponses: false,
     }),
   );
-  registerRoutes(registerRouteHandlers(API), apiRouter, {
-    serializers: {
-      "image/jpeg": (content) => {
-        return Buffer.from(content, "base64");
+
+  // Register routes by tag using registerRouteHandlersByTag
+  const petsRoutes = registerRouteHandlersByTag("pets", petsService);
+  const mediaRoutes = registerRouteHandlersByTag("media", mediaService);
+  const untaggedRoutes = registerRouteHandlersByTag(null, untaggedService);
+
+  registerRoutes(
+    [...petsRoutes, ...mediaRoutes, ...untaggedRoutes],
+    apiRouter,
+    {
+      serializers: {
+        "image/jpeg": (content) => {
+          return Buffer.from(content, "base64");
+        },
       },
     },
-  });
+  );
 
   app.use("/api/v3", apiRouter);
 

examples/tags/gen/server.ts

@@ -3,7 +3,7 @@
  * Do not make direct changes to the file.
  */
 
-import type { paths } from "./schema";
+import type { paths } from "./schema.d.ts";
 import type { Route } from "openapi-typescript-server-runtime";
 import { NotImplementedError } from "openapi-typescript-server-runtime";
 
@@ -218,23 +218,31 @@ export function registerRouteHandlers<Req, Res>(server: Server<Req, Res>): Route
   ]
 }
 
-export type Tag = null;
+export type Tag = "pets" | "media" | null;
 
-export interface ServerForUntagged<Req = unknown, Res = unknown> {
+export interface ServerForPets<Req = unknown, Res = unknown> {
   listPets: (args: ListPetsArgs<Req, Res>) => ListPetsResult;
   getPetById: (args: GetPetByIdArgs<Req, Res>) => GetPetByIdResult;
   updatePetWithForm: (args: UpdatePetWithFormArgs<Req, Res>) => UpdatePetWithFormResult;
+}
+
+export interface ServerForUntagged<Req = unknown, Res = unknown> {
   mixedContentTypes: (args: MixedContentTypesArgs<Req, Res>) => MixedContentTypesResult;
+}
+
+export interface ServerForMedia<Req = unknown, Res = unknown> {
   getPetImage: (args: GetPetImageArgs<Req, Res>) => GetPetImageResult;
   getPetWebpage: (args: GetPetWebpageArgs<Req, Res>) => GetPetWebpageResult;
 }
 
+export function registerRouteHandlersByTag<Req, Res>(tag: "pets", server: ServerForPets<Req, Res>): Route[];
 export function registerRouteHandlersByTag<Req, Res>(tag: null, server: ServerForUntagged<Req, Res>): Route[];
+export function registerRouteHandlersByTag<Req, Res>(tag: "media", server: ServerForMedia<Req, Res>): Route[];
 export function registerRouteHandlersByTag<Req, Res>(tag: Tag, server: Partial<Server<Req, Res>>): Route[] {
   const routes: Route[] = [];
 
   switch (tag) {
-    case null:
+    case "pets":
       routes.push({
         method: "get",
         path: "/pets",
@@ -250,11 +258,15 @@ export function registerRouteHandlersByTag<Req, Res>(tag: Tag, server: Partial<S
         path: "/pet/{petId}",
         handler: server.updatePetWithForm as Route["handler"],
       });
+      break;
+    case null:
       routes.push({
         method: "post",
         path: "/pet/{petId}/mixed-content-types",
         handler: server.mixedContentTypes as Route["handler"],
       });
+      break;
+    case "media":
       routes.push({
         method: "get",
         path: "/pet/{petId}/image",

examples/tags/openapi.yaml

@@ -7,6 +7,8 @@ servers:
 paths:
   /pets:
     get:
+      tags:
+        - pets
       operationId: listPets
       summary: Returns all pets from the system that the user has access to
       responses:
@@ -29,6 +31,8 @@ paths:
                 $ref: "#/components/schemas/ErrorResponse"
   /pet/{petId}:
     get:
+      tags:
+        - pets
       operationId: getPetById
       parameters:
         - name: petId
@@ -55,6 +59,8 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
     post:
+      tags:
+        - pets
       operationId: updatePetWithForm
       parameters:
         - name: petId
@@ -151,6 +157,8 @@ paths:
                 $ref: "#/components/schemas/ErrorResponse"
   /pet/{petId}/image:
     get:
+      tags:
+        - media
       operationId: getPetImage
       parameters:
         - name: petId
@@ -170,6 +178,8 @@ paths:
                 format: binary
   /pet/{petId}/webpage:
     get:
+      tags:
+        - media
       operationId: getPetWebpage
       parameters:
         - name: petId

examples/tags/package.json

@@ -21,4 +21,4 @@
     "supertest": "^7.1.4",
     "xml-js": "^1.6.11"
   }
-}
+}