🚀 Proposal: Use JSDoc Comments to Drive OpenAPI — Enable True "Contract-as-Code" with Elysia + Zod

[eastgold15]

---

🚀 Proposal: Use JSDoc Comments to Drive OpenAPI — Enable True "Contract-as-Code" with Elysia + Zod

Context: Currently, Elysia defines OpenAPI metadata via .openapi({ ... }) configuration objects. This approach separates documentation from function semantics. I propose using JSDoc comments as the source of truth for OpenAPI metadata, combined with Zod contracts, to achieve a cleaner, more maintainable full-stack developer experience.

🔗 Why This Matters

Modern frontend ecosystems (e.g., shadcn/ui + React Hook Form) widely adopt Zod for form validation.
If we use Zod on both frontend and backend to define request/response schemas, we can:

• ✅ Share types (e.g., a single UserSchema used everywhere)
• ✅ Auto-generate precise OpenAPI specs
• ️ Enable true "API-first" development

Elysia’s composable, chainable design aligns perfectly with Zod’s declarative schema style — but the current OpenAPI annotation method holds us back.

---

❌ Current Approach: Configuration Objects Intrude into Business Logic

import { Elysia } from 'elysia'
import { t } from '@elysiajs/swagger'

const app = new Elysia().post(
  '/users',
  ({ body }) => createUser(body),
  {
    body: CreateUserSchema,
    detail: {
      summary: 'Create a new user',
      description: 'Register a new user account with email and password',
      tags: ['User Management'],
      response: {
        201: t.Object({ id: t.String(), name: t.String() }),
        400: t.String({ description: 'Invalid request parameters' })
      }
    }
  }
)

⚠️ Problems:

1. Metadata pollutes business logic — core handler is buried under config.
2. Redundant definitions — Zod already describes the structure; OpenAPI repeats it with t.Object.
3. Hard to maintain — changing a description requires digging into nested objects.

---

✅ Proposed Solution: JSDoc Comments as OpenAPI Source

Inspired by Apifox and Swagger: comments are the contract.

import { Elysia } from 'elysia'

const app = new Elysia()

/**
 * @summary Create a new user
 * @description Register a new user account with email and password
 * @tags User Management
 * @response 201 - User created successfully { id: string, name: string }
 * @response 400 - Invalid request parameters
 */
.post('/users', ({ body }) => createUser(body), {
  body: CreateUserSchema // ← Only Zod contract remains
})

✨ Benefits:

• Cleaner code: business logic stays focused;
• Natural documentation: developers write JSDoc while coding;
• Tool-friendly: plugins can parse JSDoc to generate OpenAPI.

---

🔧 How Could This Work? (Conceptual Prototype)

We could build an @elysiajs/jsdoc-openapi plugin:

import swagger from '@elysiajs/swagger'
import jsdocOpenAPI from '@elysiajs/jsdoc-openapi'

new Elysia()
  .use(jsdocOpenAPI()) // ← auto-extracts JSDoc at startup
  .use(swagger())
  .post('/users', handler, { body: CreateUserSchema })
  .listen(3000)

This plugin would:

1. Statically analyze JSDoc comments above route handlers;
2. Map tags like @summary, @description, @tags, @response to OpenAPI fields;
3. Merge with Zod schemas to produce a complete spec.

💡 Zod defines structure. JSDoc defines semantics. Clean separation of concerns.

---

🌐 Full-Stack Contract Layer: Zod as the Bridge

// shared/schemas.ts
import {
  createInsertSchema,
  createSelectSchema,
  createUpdateSchema,
} from "drizzle-zod";

import { z } from "zod";
import { PaginationParams, SortParams } from "../helper/query-types";
import { heroCardsTable } from "./hero-cards.schema";
// === base Schema ===
const Insert = createInsertSchema(heroCardsTable);
const UpdateBase = createUpdateSchema(heroCardsTable);
const Select = createSelectSchema(heroCardsTable);
// === Business Schema ===
const Create = Insert.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

const Update = UpdateBase.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

const Patch = UpdateBase.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
  imageId: true,
})
  .extend({
    imageId: z.array(z.coerce.number()).optional(),
  })
  .partial();

• Frontend: Validate forms with CreateUserSchema;
• Backend: Validate request bodies with the same schema;
• OpenAPI: Auto-generate accurate models for /users;
• Apifox / Postman: Sync up-to-date API docs instantly.

✅ Write once, validate everywhere — with end-to-end type safety.

---

📣 Closing Thoughts

Elysia is already an innovative framework.
By embracing “comments as documentation” and “Zod as the universal contract”, it could become the gold standard for full-stack TypeScript development.

I’d love to hear community feedback

---

Related Links:

• shadcn/ui Form + Zod Example
• Zod to OpenAPI
• Apifox: Annotation-Driven Docs

---

Feel free to post this directly in a GitHub Discussion! Let me know if you'd like a version with syntax highlighting optimized for GitHub, or if you want help drafting a follow-up comment with a working plugin demo.