@asenajs/asena-openapi

Automatic OpenAPI 3.1 spec generation for AsenaJS — zero config, uses your existing validators.

Your existing @Controller routes and validator schemas (json(), query(), param(), response()) are automatically converted to a full OpenAPI specification. No extra annotations needed.

Features

• Zero Config - Extracts schemas from existing validators, no extra annotations needed
• OpenAPI 3.1 - Generates JSON Schema draft-2020-12 compatible spec
• Zero Runtime Dependencies - Only peer deps (asena, reflect-metadata, zod)
• Built-in Swagger UI - CDN-based UI page, no npm install required
• @Hidden Decorator - Class and method level exclusion from spec
• Zod v4 Native - Uses z.toJSONSchema() for accurate conversion
• Pluggable Converters - SchemaConverter interface for custom schema types
• IoC Integrated - PostProcessor pattern, auto-discovers controllers during bootstrap

Requirements

• Bun v1.3.12 or higher
• @asenajs/asena v0.10.0 or higher
• Zod v4.3 or higher

Installation

bun add @asenajs/asena-openapi

Quick Start

import { OpenApi, OpenApiPostProcessor } from '@asenajs/asena-openapi';

@OpenApi({
  info: { title: 'My API', version: '1.0.0' },
  path: '/api/openapi',
  ui: true, // Swagger UI at /api/openapi/ui
})
export class AppOpenApi extends OpenApiPostProcessor {}

Asena automatically discovers it — that's it.

Now:

• GET /api/openapi → OpenAPI 3.1 JSON spec
• GET /api/openapi/ui → Swagger UI page

How It Works

The OpenApiPostProcessor automatically:

1. Intercepts every @Controller during IoC setup
2. Extracts route metadata (@Get, @Post, @Put, @Delete)
3. Resolves validators and converts their Zod schemas to JSON Schema
4. Generates a complete OpenAPI 3.1 spec
5. Registers GET endpoints on the adapter for spec and Swagger UI

Your existing validators do double duty — they validate requests AND generate documentation:

@Middleware({ validator: true })
export class CreateUserValidator extends ValidationService {
  // → requestBody (application/json)
  json() {
    return z.object({
      name: z.string().min(1),
      email: z.string().email(),
    });
  }

  // → query parameters
  query() {
    return z.object({
      page: z.coerce.number().optional(),
    });
  }

  // → path parameters (only for segments the path template declares)
  param() {
    return z.object({
      id: z.string().uuid(),
    });
  }

  // → response schemas by status code
  response() {
    return {
      201: z.object({ id: z.string(), name: z.string() }),
      400: { schema: z.object({ error: z.string() }), description: 'Validation error' },
    };
  }
}

Path Parameters

Every variable in a route path is documented, whether or not a param() validator describes it. @Get('/:id') on its own emits id as a required string; a param() schema replaces that default with its own definition. A param() field the path template does not mention is dropped — OpenAPI has nowhere to put it.

Routes That Cannot Be Documented

• @All and @Connect are skipped. all and connect are not OpenAPI Path Item fields, so emitting them produces a spec that fails validation.
• Two routes claiming the same path and method throw. Generation stops and the error names both controllers, rather than letting the second writer silently overwrite the first. With OpenApiPostProcessor this surfaces on the first request to the spec endpoint, not at boot.
• operationId collisions get a numeric suffix. Two controller classes sharing a name would otherwise produce duplicate ids, which OpenAPI forbids. The first occurrence keeps the bare id.

@Hidden

Hide controllers or individual routes from the spec:

// Hide entire controller
@Hidden()
@Controller('/internal')
export class InternalController { ... }

// Hide single route
@Controller('/api')
export class ApiController {
  @Hidden()
  @Get('/health')
  healthCheck() {}

  @Get('/users')  // this route IS in the spec
  listUsers() {}
}

Configuration

OpenApiDecoratorOptions

@OpenApi({
  info: {
    title: 'My API', // Required
    version: '1.0.0', // Required
    description: 'My app', // Optional
  },
  path: '/api/openapi', // Default: '/openapi'
  ui: true, // Default: false — enables Swagger UI at {path}/ui
  servers: [
    // Optional
    { url: 'https://api.example.com', description: 'Production' },
  ],
  converters: [
    // Default: [ZodSchemaConverter]
    new ZodSchemaConverter(),
  ],
})
export class AppOpenApi extends OpenApiPostProcessor {}

Swagger UI

When ui: true, a Swagger UI page is served at {path}/ui. It loads from CDN — zero npm dependencies:

• Uses swagger-ui-dist@5 from unpkg CDN
• No build step required
• Works in development and production

OpenApiGenerator (Legacy)

For manual spec generation without the PostProcessor:

import { OpenApiGenerator, ZodSchemaConverter } from '@asenajs/asena-openapi';

const generator = new OpenApiGenerator({
  info: { title: 'My API', version: '1.0.0' },
  converters: [new ZodSchemaConverter()],
});

const spec = await generator.generate(server.coreContainer.container);

Both builders share one internal operation builder, so a route documents identically either way.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Maintain test coverage for critical paths
2. Follow existing code style and linting rules
3. Test with both Hono and Ergenecore adapters

Submit a Pull Request on GitHub.

License

MIT

Support

Issues or questions? Open an issue on GitHub.