Guard Schema OpenAPI Fix - Reproduction Demo

This project demonstrates the fix for guard() schemas not appearing in OpenAPI documentation.

Issue

When using guard() to apply validation schemas to multiple routes, those schemas were not included in the generated OpenAPI specification.

Solution

• Elysia Core: Added getFlattenedRoutes() method that merges standaloneValidator arrays into direct hook properties
• OpenAPI Plugin: Updated to use getFlattenedRoutes() instead of getGlobalRoutes()

Setup

This demo uses local versions of both packages with the fixes applied.

# Install dependencies (links to local elysia and elysia-openapi)
bun install

# Run the server
bun run dev

# Test the fix
bun run test:after

Verification Steps

1. Start the Server

bun run dev

Server will start at http://localhost:3000

2. Check OpenAPI Docs

Open http://localhost:3000/docs or fetch the JSON:

curl http://localhost:3000/docs/json | jq '.paths'

3. Verify Schemas Appear

Check that /sign-up and /sign-in endpoints now include requestBody schemas:

{
  "/sign-up": {
    "post": {
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "username": { "type": "string" },
                "password": { "type": "string" }
              },
              "required": ["username", "password"]
            }
          }
        },
        "required": true
      },
      "operationId": "postSign-up"
    }
  }
}

4. Test Route Functionality

# Test sign-up
curl -X POST http://localhost:3000/sign-up \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

# Test sign-in
curl -X POST http://localhost:3000/sign-in \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

Testing the Fix Directly

Run the test script to see the internal behavior:

bun run test:after

This shows:

• Normal routes (via getGlobalRoutes()) have standaloneValidator arrays but no direct body schemas
• Flattened routes (via getFlattenedRoutes()) have body schemas merged into direct properties
• OpenAPI plugin can now read these schemas

Files

• src/index.ts - Main server demonstrating the guard() usage
• src/test-after-fix.ts - Direct test of getFlattenedRoutes() functionality
• ADR.md - Technical decision record explaining the implementation
• package.json - Links to local fixed versions of elysia and @elysiajs/openapi

Related Changes

Elysia Core

File: src/index.ts

• Added getFlattenedRoutes() method (lines 343-354)
• Added mergeStandaloneValidators() helper (lines 359-405)
• Added mergeSchemaProperty() helper (lines 410-437)
• Added mergeResponseSchema() helper (lines 442-482)

Tests: test/core/flattened-routes.test.ts (7 tests, all passing)

OpenAPI Plugin

File: src/openapi.ts

Changed line 298 from:

const routes = app.getGlobalRoutes()

To:

const routes = app.getFlattenedRoutes?.() ?? app.getGlobalRoutes()

Contributing

To use this fix in your own projects before it's officially released:

1. Clone and build elysia with the changes
2. Clone and build elysia-openapi with the changes
3. Link them locally or copy the built files

Or wait for the PRs to be merged and new versions to be published.