@onebun/docs 0.1.2 → 0.1.3

package/README.md

@@ -4,12 +4,11 @@ Documentation generation package for OneBun framework with OpenAPI/Swagger suppo
 
 ## Features
 
-- 📖 **OpenAPI Generation** - Automatic OpenAPI 3.0 specification from decorators
-- 🎨 **Swagger UI** - Built-in Swagger UI for interactive API documentation
-- 🔄 **JSON Schema Converter** - Convert validation schemas to JSON Schema format
-- 🏷️ **Decorator-based** - Use decorators to document your API endpoints
-- 📝 **Type-safe** - Full TypeScript support with type inference
-- ⚡ **Effect.js Integration** - Seamless integration with Effect.js ecosystem
+- OpenAPI Generation - Automatic OpenAPI 3.1 specification from decorators
+- Swagger UI - Built-in Swagger UI HTML generation for interactive API documentation
+- JSON Schema Converter - Convert ArkType validation schemas to JSON Schema format
+- Decorator-based - Use decorators to add metadata for documentation
+- Type-safe - Full TypeScript support with type inference
 
 ## Installation
 
@@ -21,178 +20,212 @@ bun add @onebun/docs
 
 ### Basic Usage
 
+The `@onebun/docs` package provides decorators for adding documentation metadata to your controllers. Note that `@ApiResponse` for response validation is provided by `@onebun/core`.
+
+**Important: Decorator Order Matters!**
+- `@ApiTags` must be placed **above** `@Controller` (because `@Controller` wraps the class)
+- `@ApiOperation` must be placed **above** route decorators (`@Get`, `@Post`, etc.)
+- `@ApiResponse` must be placed **below** route decorators
+
 ```typescript
-import { OneBunApplication, Controller, Get, Post, Body } from '@onebun/core';
-import { ApiTag, ApiOperation, ApiResponse, ApiBody } from '@onebun/docs';
+import { Controller, Get, Post, Body, BaseController, ApiResponse } from '@onebun/core';
+import { ApiTags, ApiOperation } from '@onebun/docs';
+import { type } from 'arktype';
+
+const createUserSchema = type({
+  name: 'string',
+  email: 'string.email',
+});
 
+// @ApiTags ABOVE @Controller
+@ApiTags('Users')
 @Controller('/users')
-@ApiTag('Users', 'User management endpoints')
-export class UserController {
-  @Get()
+export class UserController extends BaseController {
+  // @ApiOperation ABOVE @Get, @ApiResponse BELOW @Get
   @ApiOperation({ summary: 'Get all users', description: 'Returns a list of all users' })
-  @ApiResponse({ status: 200, description: 'List of users returned successfully' })
-  async getUsers() {
-    return { users: [] };
+  @Get('/')
+  @ApiResponse(200, { description: 'List of users returned successfully' })
+  async getUsers(): Promise<Response> {
+    return this.success({ users: [] });
   }
 
-  @Post()
   @ApiOperation({ summary: 'Create user', description: 'Creates a new user' })
-  @ApiBody({ description: 'User data', required: true })
-  @ApiResponse({ status: 201, description: 'User created successfully' })
-  @ApiResponse({ status: 400, description: 'Invalid input data' })
-  async createUser(@Body() userData: CreateUserDto) {
-    return { id: '1', ...userData };
+  @Post('/')
+  @ApiResponse(201, { schema: createUserSchema, description: 'User created successfully' })
+  @ApiResponse(400, { description: 'Invalid input data' })
+  async createUser(@Body(createUserSchema) userData: typeof createUserSchema.infer): Promise<Response> {
+    return this.success({ id: '1', ...userData });
   }
 }
 ```
 
-### Enable Swagger UI
+## Decorators
+
+### From @onebun/docs
+
+#### @ApiTags(...tags)
+
+Group endpoints under tags. Can be used on controller class or individual methods.
 
 ```typescript
-import { OneBunApplication } from '@onebun/core';
-import { AppModule } from './app.module';
-
-const app = new OneBunApplication(AppModule, {
-  docs: {
-    enabled: true,
-    path: '/docs',
-    title: 'My API',
-    version: '1.0.0',
-    description: 'API documentation for my service'
-  }
-});
+import { ApiTags } from '@onebun/docs';
 
-await app.start();
-// Swagger UI available at http://localhost:3000/docs
+// @ApiTags must be ABOVE @Controller
+@ApiTags('Users', 'User Management')
+@Controller('/users')
+export class UserController extends BaseController {
+  // All endpoints in this controller will be tagged with 'Users' and 'User Management'
+}
 ```
 
-## Decorators
+#### @ApiOperation(options)
 
-### Controller Level
+Describe an API operation with summary, description, and additional tags.
 
-- `@ApiTag(name, description?)` - Group endpoints under a tag
+```typescript
+import { ApiOperation } from '@onebun/docs';
+
+// @ApiOperation must be ABOVE route decorator
+@ApiOperation({
+  summary: 'Get user by ID',
+  description: 'Returns a single user by their unique identifier',
+  tags: ['Users'],  // Additional tags for this specific endpoint
+})
+@Get('/:id')
+async getUser(@Param('id') id: string): Promise<Response> {
+  // ...
+}
+```
 
-### Method Level
+### From @onebun/core
 
-- `@ApiOperation(options)` - Describe the operation
-- `@ApiResponse(options)` - Document response types
-- `@ApiBody(options)` - Document request body
-- `@ApiParam(options)` - Document path parameters
-- `@ApiQuery(options)` - Document query parameters
-- `@ApiHeader(options)` - Document header parameters
+#### @ApiResponse(statusCode, options?)
 
-## Configuration Options
+Document and validate response types. This decorator is provided by `@onebun/core`.
 
 ```typescript
-interface DocsOptions {
-  // Enable/disable documentation (default: true)
-  enabled?: boolean;
-
-  // Path for Swagger UI (default: '/docs')
-  path?: string;
-
-  // API title
-  title?: string;
-
-  // API version
-  version?: string;
-
-  // API description
-  description?: string;
-
-  // Contact information
-  contact?: {
-    name?: string;
-    email?: string;
-    url?: string;
-  };
-
-  // License information
-  license?: {
-    name: string;
-    url?: string;
-  };
-
-  // External documentation
-  externalDocs?: {
-    description?: string;
-    url: string;
-  };
-
-  // Server URLs
-  servers?: Array<{
-    url: string;
-    description?: string;
-  }>;
+import { ApiResponse } from '@onebun/core';
+import { type } from 'arktype';
+
+const userSchema = type({
+  id: 'string',
+  name: 'string',
+  email: 'string.email',
+});
+
+// @ApiResponse must be BELOW route decorator
+@Get('/:id')
+@ApiResponse(200, { schema: userSchema, description: 'User found' })
+@ApiResponse(404, { description: 'User not found' })
+async getUser(@Param('id') id: string): Promise<Response> {
+  // Response will be validated against userSchema for 200 responses
 }
 ```
 
 ## OpenAPI Generation
 
-### Programmatic Access
+### Generate OpenAPI Spec from Controllers
 
 ```typescript
 import { generateOpenApiSpec } from '@onebun/docs';
+import { UserController } from './user.controller';
+import { OrderController } from './order.controller';
 
-const spec = generateOpenApiSpec(AppModule, {
+const spec = generateOpenApiSpec([UserController, OrderController], {
   title: 'My API',
-  version: '1.0.0'
+  version: '1.0.0',
+  description: 'API documentation for my service',
 });
 
 // Save to file
 await Bun.write('openapi.json', JSON.stringify(spec, null, 2));
 ```
 
-### JSON Schema Conversion
+### Generate Swagger UI HTML
 
 ```typescript
-import { toJsonSchema } from '@onebun/docs';
-import { S } from '@onebun/core';
+import { generateSwaggerUiHtml } from '@onebun/docs';
 
-const userSchema = S.object({
-  id: S.string(),
-  email: S.string().email(),
-  age: S.number().min(0).max(150)
-});
+// Generate HTML that loads OpenAPI spec from a URL
+const html = generateSwaggerUiHtml('/openapi.json');
 
-const jsonSchema = toJsonSchema(userSchema);
-// Returns JSON Schema compatible object
+// Serve as an endpoint
+@Get('/docs')
+async getDocs(): Promise<Response> {
+  return new Response(html, {
+    headers: { 'Content-Type': 'text/html' },
+  });
+}
 ```
 
-## Integration with Validation
+### JSON Schema Conversion
 
-The docs package works seamlessly with `@onebun/core` validation schemas:
+Convert ArkType schemas to JSON Schema format for OpenAPI documentation:
 
 ```typescript
-import { Controller, Post, Body, S } from '@onebun/core';
-import { ApiOperation, ApiBody, ApiResponse } from '@onebun/docs';
+import { arktypeToJsonSchema } from '@onebun/docs';
+import { type } from 'arktype';
 
-const CreateUserSchema = S.object({
-  name: S.string().min(1).max(100),
-  email: S.string().email(),
-  age: S.number().optional()
+const userSchema = type({
+  id: 'string',
+  email: 'string.email',
+  age: 'number > 0',
 });
 
-@Controller('/users')
-export class UserController {
-  @Post()
-  @ApiOperation({ summary: 'Create user' })
-  @ApiBody({ schema: CreateUserSchema })
-  @ApiResponse({ status: 201, schema: CreateUserSchema })
-  async createUser(@Body(CreateUserSchema) userData: typeof CreateUserSchema.infer) {
-    return userData;
-  }
-}
+const jsonSchema = arktypeToJsonSchema(userSchema);
+// Returns JSON Schema compatible object
 ```
 
+## Integration with @onebun/core
+
+The docs package reads metadata from `@onebun/core` decorators automatically:
+
+- Route information from `@Get`, `@Post`, `@Put`, `@Delete`, `@Patch`
+- Path parameters from `@Param`
+- Query parameters from `@Query`
+- Request body from `@Body`
+- Response schemas from `@ApiResponse`
+
+This means your existing controller decorators contribute to the generated OpenAPI spec.
+
 ## Best Practices
 
-1. **Document all endpoints** - Add at least `@ApiOperation` and `@ApiResponse` to every endpoint
-2. **Use meaningful descriptions** - Help consumers understand your API
-3. **Group related endpoints** - Use `@ApiTag` for logical grouping
-4. **Document error responses** - Include common error status codes
+1. **Use @ApiOperation for all endpoints** - Add summary and description
+2. **Use @ApiTags for grouping** - Group related endpoints logically
+3. **Document response types** - Use `@ApiResponse` with schemas from `@onebun/core`
+4. **Use meaningful descriptions** - Help API consumers understand your endpoints
 5. **Keep documentation updated** - Decorators ensure docs stay in sync with code
 
+## API Reference
+
+### generateOpenApiSpec(controllers, options)
+
+Generate OpenAPI 3.1 specification from controller classes.
+
+**Parameters:**
+- `controllers: Function[]` - Array of controller classes
+- `options: { title?: string; version?: string; description?: string }` - OpenAPI info options
+
+**Returns:** `OpenApiSpec` - OpenAPI 3.1 compliant specification object
+
+### generateSwaggerUiHtml(specUrl)
+
+Generate HTML page with Swagger UI.
+
+**Parameters:**
+- `specUrl: string` - URL to the OpenAPI JSON specification
+
+**Returns:** `string` - HTML string
+
+### arktypeToJsonSchema(schema)
+
+Convert ArkType schema to JSON Schema.
+
+**Parameters:**
+- `schema: Type<unknown>` - ArkType schema
+
+**Returns:** `Record<string, unknown>` - JSON Schema object
+
 ## License
 
 [LGPL-3.0](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/docs",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Documentation generation for OneBun framework - OpenAPI, Swagger UI",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -41,6 +41,7 @@
     "swagger-ui-dist": "^5.17.14"
   },
   "devDependencies": {
+    "arktype": "^2.0.0",
     "bun-types": "1.2.2"
   },
   "engines": {

package/src/decorators.ts

@@ -72,24 +72,58 @@ export function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator {
 
 /**
  * Get API operation metadata for a method
+ * Walks up the prototype chain to find metadata (needed because @Controller wraps classes)
  */
 export function getApiOperationMetadata(
   target: object,
   propertyKey: string | symbol,
 ): { summary?: string; description?: string; tags?: string[] } | undefined {
-  return getMetadata(API_OPERATION_METADATA, target, propertyKey);
+  // Try to get metadata from target directly
+  let result = getMetadata(API_OPERATION_METADATA, target, propertyKey);
+  if (result) {
+    return result;
+  }
+
+  // Walk up prototype chain (needed for wrapped classes)
+  let proto = Object.getPrototypeOf(target);
+  while (proto && proto !== Object.prototype) {
+    result = getMetadata(API_OPERATION_METADATA, proto, propertyKey);
+    if (result) {
+      return result;
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return undefined;
 }
 
 /**
  * Get API tags for a class or method
+ * Walks up the prototype chain to find metadata (needed because @Controller wraps classes)
  */
 export function getApiTagsMetadata(
   target: object | Function,
   propertyKey?: string | symbol,
 ): string[] | undefined {
   if (propertyKey !== undefined) {
-    return getMetadata(API_TAGS_METADATA, target, propertyKey);
+    // Method-level tags - walk prototype chain
+    let result = getMetadata(API_TAGS_METADATA, target, propertyKey);
+    if (result) {
+      return result;
+    }
+
+    let proto = Object.getPrototypeOf(target);
+    while (proto && proto !== Object.prototype) {
+      result = getMetadata(API_TAGS_METADATA, proto, propertyKey);
+      if (result) {
+        return result;
+      }
+      proto = Object.getPrototypeOf(proto);
+    }
+
+    return undefined;
   }
 
+  // Class-level tags
   return getMetadata(API_TAGS_METADATA, target);
 }

package/src/docs-examples.test.ts

@@ -4,160 +4,186 @@
  * This file tests code examples from:
  * - packages/docs/README.md
  *
- * Note: The README describes more decorators than are currently implemented.
- * This test file tests the actually available decorators.
+ * The \@onebun/docs package provides:
+ * - \@ApiTags - for grouping endpoints
+ * - \@ApiOperation - for describing operations
+ * - generateOpenApiSpec - for generating OpenAPI specs
+ * - generateSwaggerUiHtml - for generating Swagger UI
+ * - arktypeToJsonSchema - for converting schemas
+ *
+ * Note: \@ApiResponse is provided by \@onebun/core for response validation
  */
 
+import { type } from 'arktype';
 import {
   describe,
-  it,
   expect,
+  it,
 } from 'bun:test';
 
-import { ApiOperation, ApiTags } from './decorators';
-
-/* eslint-disable @typescript-eslint/naming-convention, @typescript-eslint/no-empty-function */
-// Mock decorators for the ones that aren't implemented yet
-// These are described in README but not yet implemented
-const ApiResponse = (_options: { status: number; description: string }) =>
-  (_target: object, _propertyKey?: string | symbol) => {};
-const ApiBody = (_options: { description?: string; required?: boolean }) =>
-  (_target: object, _propertyKey?: string | symbol) => {};
-const ApiParam = (_options: { name: string; description?: string }) =>
-  (_target: object, _propertyKey?: string | symbol) => {};
-const ApiQuery = (_options: { name: string; description?: string }) =>
-  (_target: object, _propertyKey?: string | symbol) => {};
-const ApiHeader = (_options: { name: string; description?: string }) =>
-  (_target: object, _propertyKey?: string | symbol) => {};
-const ApiTag = ApiTags; // Alias for the actual implementation
-/* eslint-enable @typescript-eslint/naming-convention, @typescript-eslint/no-empty-function */
-
-describe('Docs README Examples', () => {
-  describe('Controller Level Decorators (README)', () => {
-    it('should have @ApiTag decorator available', () => {
-      // From README: Controller Level - @ApiTag
-      expect(ApiTag).toBeDefined();
-      expect(typeof ApiTag).toBe('function');
-    });
+import {
+  ApiResponse,
+  BaseController,
+  Body,
+  Controller,
+  Get,
+  Param,
+  Post,
+} from '@onebun/core';
 
-    it('should use @ApiTag decorator on controller', () => {
-      // From README: Basic Usage example
-      @ApiTag('Users', 'User management endpoints')
-      class UserController {}
+import {
+  ApiOperation,
+  ApiTags,
+  getApiOperationMetadata,
+  getApiTagsMetadata,
+} from './decorators';
+import { generateOpenApiSpec } from './openapi/generator';
+import { arktypeToJsonSchema } from './openapi/json-schema-converter';
+import { generateSwaggerUiHtml } from './openapi/swagger-ui';
 
-      expect(UserController).toBeDefined();
+describe('Docs README Examples', () => {
+  describe('Decorators from @onebun/docs', () => {
+    it('should have @ApiTags decorator available', () => {
+      expect(ApiTags).toBeDefined();
+      expect(typeof ApiTags).toBe('function');
     });
-  });
 
-  describe('Method Level Decorators (README)', () => {
     it('should have @ApiOperation decorator available', () => {
-      // From README: Method Level - @ApiOperation
       expect(ApiOperation).toBeDefined();
       expect(typeof ApiOperation).toBe('function');
     });
 
-    it('should have @ApiResponse decorator available', () => {
-      // From README: Method Level - @ApiResponse
-      expect(ApiResponse).toBeDefined();
-      expect(typeof ApiResponse).toBe('function');
-    });
+    it('should use @ApiTags on controller class', () => {
+      @ApiTags('Users')
+      class UserController {}
 
-    it('should have @ApiBody decorator available', () => {
-      // From README: Method Level - @ApiBody
-      expect(ApiBody).toBeDefined();
-      expect(typeof ApiBody).toBe('function');
+      const tags = getApiTagsMetadata(UserController);
+      expect(tags).toBeDefined();
+      expect(tags!.length).toBeGreaterThan(0);
+      expect(tags).toContain('Users');
     });
 
-    it('should have @ApiParam decorator available', () => {
-      // From README: Method Level - @ApiParam
-      expect(ApiParam).toBeDefined();
-      expect(typeof ApiParam).toBe('function');
+    it('should use @ApiTags with multiple tags', () => {
+      @ApiTags('Users', 'User Management')
+      class UserController {}
+
+      const tags = getApiTagsMetadata(UserController);
+      expect(tags).toBeDefined();
+      expect(tags).toContain('Users');
+      expect(tags).toContain('User Management');
     });
 
-    it('should have @ApiQuery decorator available', () => {
-      // From README: Method Level - @ApiQuery
-      expect(ApiQuery).toBeDefined();
-      expect(typeof ApiQuery).toBe('function');
+    it('should use @ApiOperation on method', () => {
+      class TestController {
+        @ApiOperation({
+          summary: 'Get all users',
+          description: 'Returns a list of all users',
+        })
+        async getUsers() {
+          return [];
+        }
+      }
+
+      const metadata = getApiOperationMetadata(
+        TestController.prototype,
+        'getUsers',
+      );
+      expect(metadata?.summary).toBe('Get all users');
+      expect(metadata?.description).toBe('Returns a list of all users');
     });
 
-    it('should have @ApiHeader decorator available', () => {
-      // From README: Method Level - @ApiHeader
-      expect(ApiHeader).toBeDefined();
-      expect(typeof ApiHeader).toBe('function');
+    it('should use @ApiOperation with tags', () => {
+      class TestController {
+        @ApiOperation({
+          summary: 'Get user',
+          tags: ['Users', 'Admin'],
+        })
+        async getUser() {
+          return {};
+        }
+      }
+
+      const metadata = getApiOperationMetadata(
+        TestController.prototype,
+        'getUser',
+      );
+      expect(metadata?.tags).toContain('Users');
+      expect(metadata?.tags).toContain('Admin');
     });
   });
 
   describe('Basic Usage Example (README)', () => {
-    it('should use decorators on controller methods', () => {
-      // From README: Basic Usage example
-      interface CreateUserDto {
-        name: string;
-        email: string;
-      }
-
-      @ApiTag('Users', 'User management endpoints')
-      class UserController {
+    it('should use decorators from both packages', () => {
+      const createUserSchema = type({
+        name: 'string',
+        email: 'string.email',
+      });
+
+      // Note: @ApiTags must be ABOVE @Controller because @Controller wraps the class
+      // Decorators are applied bottom-to-top, so @ApiTags runs last and gets the wrapped class
+      @ApiTags('Users')
+      @Controller('/users')
+      class UserController extends BaseController {
+        // Note: @ApiOperation must be ABOVE @Get for the same reason
         @ApiOperation({
           summary: 'Get all users',
           description: 'Returns a list of all users',
         })
-        @ApiResponse({ status: 200, description: 'List of users returned successfully' })
-        async getUsers() {
-          return { users: [] };
+        @ApiResponse(200, { description: 'List of users returned successfully' })
+        @Get('/')
+        async getUsers(): Promise<Response> {
+          return this.success({ users: [] });
         }
 
-        @ApiOperation({ summary: 'Create user', description: 'Creates a new user' })
-        @ApiBody({ description: 'User data', required: true })
-        @ApiResponse({ status: 201, description: 'User created successfully' })
-        @ApiResponse({ status: 400, description: 'Invalid input data' })
-        async createUser(userData: CreateUserDto) {
-          return { id: '1', ...userData };
+        @ApiOperation({
+          summary: 'Create user',
+          description: 'Creates a new user',
+        })
+        @ApiResponse(201, {
+          schema: createUserSchema,
+          description: 'User created successfully',
+        })
+        @ApiResponse(400, { description: 'Invalid input data' })
+        @Post('/')
+        async createUser(
+          @Body(createUserSchema) userData: typeof createUserSchema.infer,
+        ): Promise<Response> {
+          return this.success({ id: '1', ...userData });
         }
       }
 
       expect(UserController).toBeDefined();
+      
+      // Verify tags are set on controller
+      const tags = getApiTagsMetadata(UserController);
+      expect(tags).toBeDefined();
+      expect(tags!.length).toBeGreaterThan(0);
     });
   });
 
   describe('Configuration Options (README)', () => {
     it('should define valid DocsOptions interface', () => {
-      // From README: Configuration Options
+      // This matches the DocsApplicationOptions interface in core
       const docsOptions = {
-        // Enable/disable documentation (default: true)
         enabled: true,
-
-        // Path for Swagger UI (default: '/docs')
         path: '/docs',
-
-        // API title
+        jsonPath: '/openapi.json',
         title: 'My API',
-
-        // API version
         version: '1.0.0',
-
-        // API description
         description: 'API documentation for my service',
-
-        // Contact information
         contact: {
           name: 'API Support',
           email: 'support@example.com',
           url: 'https://example.com/support',
         },
-
-        // License information
         license: {
           name: 'MIT',
           url: 'https://opensource.org/licenses/MIT',
         },
-
-        // External documentation
         externalDocs: {
           description: 'More information',
           url: 'https://example.com/docs',
         },
-
-        // Server URLs
         servers: [
           {
             url: 'https://api.example.com',
@@ -172,196 +198,278 @@ describe('Docs README Examples', () => {
 
       expect(docsOptions.enabled).toBe(true);
       expect(docsOptions.path).toBe('/docs');
+      expect(docsOptions.jsonPath).toBe('/openapi.json');
       expect(docsOptions.title).toBe('My API');
       expect(docsOptions.version).toBe('1.0.0');
       expect(docsOptions.servers).toHaveLength(2);
     });
   });
+});
 
-  describe('Best Practices (README)', () => {
-    it('should document all endpoints', () => {
-      // From README: Best Practices
-      // 1. Document all endpoints - Add at least @ApiOperation and @ApiResponse
-      class BestPracticeController {
-        @ApiOperation({ summary: 'Get resource' })
-        @ApiResponse({ status: 200, description: 'Resource found' })
-        @ApiResponse({ status: 404, description: 'Resource not found' })
-        async getResource() {
-          return {};
+describe('OpenAPI Generation', () => {
+  describe('generateOpenApiSpec', () => {
+    it('should generate spec from controllers', () => {
+      // Note: @ApiTags must be ABOVE @Controller
+      @ApiTags('Users')
+      @Controller('/users')
+      class UserController extends BaseController {
+        @ApiOperation({ summary: 'Get all users' })
+        @Get('/')
+        async getUsers(): Promise<Response> {
+          return this.success([]);
+        }
+
+        @ApiOperation({ summary: 'Get user by ID' })
+        @Get('/:id')
+        async getUser(@Param('id') id: string): Promise<Response> {
+          return this.success({ id });
         }
       }
 
-      expect(BestPracticeController).toBeDefined();
+      const spec = generateOpenApiSpec([UserController], {
+        title: 'Test API',
+        version: '1.0.0',
+        description: 'Test API description',
+      });
+
+      expect(spec.openapi).toBe('3.1.0');
+      expect(spec.info.title).toBe('Test API');
+      expect(spec.info.version).toBe('1.0.0');
+      expect(spec.info.description).toBe('Test API description');
+      expect(spec.paths).toBeDefined();
+      // Controller path + route path = /users + / = /users/
+      expect(spec.paths['/users/']).toBeDefined();
+      expect(spec.paths['/users/:id']).toBeDefined();
     });
 
-    it('should use meaningful descriptions', () => {
-      // From README: Best Practices
-      // 2. Use meaningful descriptions - Help consumers understand your API
-      class DescriptiveController {
-        @ApiOperation({
-          summary: 'Create a new user account',
-          description:
-            'Creates a new user account with the provided email and password. ' +
-            'The email must be unique and a valid email format. ' +
-            'Password must be at least 8 characters.',
-        })
-        @ApiResponse({
-          status: 201,
-          description: 'User account created successfully. Returns the new user object.',
-        })
-        @ApiResponse({
-          status: 400,
-          description: 'Invalid input - email format incorrect or password too short.',
-        })
-        @ApiResponse({
-          status: 409,
-          description: 'Conflict - a user with this email already exists.',
-        })
-        async createUser() {
-          return {};
+    it('should include tags from @ApiTags', () => {
+      @ApiTags('Orders')
+      @Controller('/orders')
+      class OrderController extends BaseController {
+        @ApiOperation({ summary: 'Get orders' })
+        @Get('/')
+        async getOrders(): Promise<Response> {
+          return this.success([]);
         }
       }
 
-      expect(DescriptiveController).toBeDefined();
+      const spec = generateOpenApiSpec([OrderController], {
+        title: 'Test API',
+        version: '1.0.0',
+      });
+
+      // Path is /orders/ (controller path + route path)
+      const getOperation = spec.paths['/orders/']?.get;
+      expect(getOperation).toBeDefined();
+      expect(getOperation?.tags).toBeDefined();
+      expect(getOperation?.tags).toContain('Orders');
     });
 
-    it('should group related endpoints', () => {
-      // From README: Best Practices
-      // 3. Group related endpoints - Use @ApiTag for logical grouping
-      @ApiTag('Users', 'Operations related to user management')
-      class UsersController {
-        async getUsers() {
-          return []; 
-        }
-        async createUser() {
-          return {}; 
-        }
-        async updateUser() {
-          return {}; 
-        }
-        async deleteUser() {
-          return {}; 
+    it('should include operation metadata from @ApiOperation', () => {
+      @Controller('/products')
+      class ProductController extends BaseController {
+        @ApiOperation({
+          summary: 'List products',
+          description: 'Returns paginated list of products',
+          tags: ['Products', 'Catalog'],
+        })
+        @Get('/')
+        async listProducts(): Promise<Response> {
+          return this.success([]);
         }
       }
 
-      @ApiTag('Orders', 'Operations related to order management')
-      class OrdersController {
-        async getOrders() {
-          return []; 
-        }
-        async createOrder() {
-          return {}; 
+      const spec = generateOpenApiSpec([ProductController], {
+        title: 'Test API',
+        version: '1.0.0',
+      });
+
+      const getOperation = spec.paths['/products/']?.get;
+      expect(getOperation).toBeDefined();
+      expect(getOperation?.summary).toBe('List products');
+      expect(getOperation?.description).toBe(
+        'Returns paginated list of products',
+      );
+      expect(getOperation?.tags).toContain('Products');
+      expect(getOperation?.tags).toContain('Catalog');
+    });
+
+    it('should include response schemas from @ApiResponse', () => {
+      const productSchema = type({
+        id: 'string',
+        name: 'string',
+        price: 'number',
+      });
+
+      @Controller('/products')
+      class ProductController extends BaseController {
+        // Note: @Get must be ABOVE @ApiResponse because @Get reads response schemas when it runs
+        // and decorators apply bottom-to-top
+        @Get('/:id')
+        @ApiResponse(200, {
+          schema: productSchema,
+          description: 'Product found',
+        })
+        @ApiResponse(404, { description: 'Product not found' })
+        async getProduct(@Param('id') id: string): Promise<Response> {
+          return this.success({ id, name: 'Test', price: 10 });
         }
       }
 
-      expect(UsersController).toBeDefined();
-      expect(OrdersController).toBeDefined();
+      const spec = generateOpenApiSpec([ProductController], {
+        title: 'Test API',
+        version: '1.0.0',
+      });
+
+      const responses = spec.paths['/products/:id']?.get?.responses;
+      expect(responses?.['200']).toBeDefined();
+      expect(responses?.['200']?.description).toBe('Product found');
+      expect(responses?.['404']).toBeDefined();
+      expect(responses?.['404']?.description).toBe('Product not found');
     });
 
-    it('should document error responses', () => {
-      // From README: Best Practices
-      // 4. Document error responses - Include common error status codes
-      class ErrorDocumentedController {
-        @ApiOperation({ summary: 'Update user' })
-        @ApiResponse({ status: 200, description: 'User updated successfully' })
-        @ApiResponse({ status: 400, description: 'Invalid request body' })
-        @ApiResponse({ status: 401, description: 'Authentication required' })
-        @ApiResponse({ status: 403, description: 'Permission denied' })
-        @ApiResponse({ status: 404, description: 'User not found' })
-        @ApiResponse({ status: 422, description: 'Validation error' })
-        @ApiResponse({ status: 500, description: 'Internal server error' })
-        async updateUser() {
-          return {};
+    it('should use default options when not provided', () => {
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/health')
+        async health(): Promise<Response> {
+          return this.success({ status: 'ok' });
         }
       }
 
-      expect(ErrorDocumentedController).toBeDefined();
+      const spec = generateOpenApiSpec([ApiController]);
+
+      expect(spec.info.title).toBe('OneBun API');
+      expect(spec.info.version).toBe('1.0.0');
     });
   });
-});
 
-describe('Decorator Options', () => {
-  describe('@ApiOperation options', () => {
-    it('should accept summary and description', () => {
-      class TestController {
-        @ApiOperation({
-          summary: 'Short summary',
-          description: 'Longer description with more details',
-        })
-        async testMethod() {}
-      }
+  describe('generateSwaggerUiHtml', () => {
+    it('should generate valid HTML', () => {
+      const html = generateSwaggerUiHtml('/openapi.json');
 
-      expect(TestController).toBeDefined();
+      expect(html).toContain('<!DOCTYPE html>');
+      expect(html).toContain('swagger-ui');
+      expect(html).toContain('/openapi.json');
     });
-  });
 
-  describe('@ApiResponse options', () => {
-    it('should accept status and description', () => {
-      class TestController {
-        @ApiResponse({
-          status: 200,
-          description: 'Success response',
-        })
-        async testMethod() {}
-      }
+    it('should include spec URL in SwaggerUI config', () => {
+      const html = generateSwaggerUiHtml('/api/v1/openapi.json');
 
-      expect(TestController).toBeDefined();
+      expect(html).toContain('url: "/api/v1/openapi.json"');
     });
   });
 
-  describe('@ApiBody options', () => {
-    it('should accept description and required', () => {
-      class TestController {
-        @ApiBody({
-          description: 'Request body',
-          required: true,
-        })
-        async testMethod() {}
-      }
+  describe('arktypeToJsonSchema', () => {
+    it('should convert simple object schema', () => {
+      const userSchema = type({
+        name: 'string',
+        age: 'number',
+      });
+
+      const jsonSchema = arktypeToJsonSchema(userSchema);
 
-      expect(TestController).toBeDefined();
+      expect(jsonSchema.type).toBe('object');
+      expect(jsonSchema.properties).toBeDefined();
     });
-  });
 
-  describe('@ApiParam options', () => {
-    it('should accept name and description', () => {
-      class TestController {
-        @ApiParam({
-          name: 'id',
-          description: 'Resource ID',
-        })
-        async testMethod() {}
-      }
+    it('should convert schema with string constraints', () => {
+      const emailSchema = type('string.email');
+
+      const jsonSchema = arktypeToJsonSchema(emailSchema);
+
+      expect(jsonSchema).toBeDefined();
+    });
+
+    it('should convert nested object schema', () => {
+      const addressSchema = type({
+        street: 'string',
+        city: 'string',
+      });
+
+      const userSchema = type({
+        name: 'string',
+        address: addressSchema,
+      });
+
+      const jsonSchema = arktypeToJsonSchema(userSchema);
 
-      expect(TestController).toBeDefined();
+      expect(jsonSchema.type).toBe('object');
+      expect(jsonSchema.properties).toBeDefined();
     });
   });
+});
 
-  describe('@ApiQuery options', () => {
-    it('should accept name and description', () => {
-      class TestController {
-        @ApiQuery({
-          name: 'page',
-          description: 'Page number',
-        })
-        async testMethod() {}
+describe('Best Practices (README)', () => {
+  it('should use @ApiOperation for all endpoints', () => {
+    @Controller('/resources')
+    class ResourceController extends BaseController {
+      @ApiOperation({ summary: 'List resources' })
+      @ApiResponse(200, { description: 'Resources listed' })
+      @Get('/')
+      async list(): Promise<Response> {
+        return this.success([]);
       }
 
-      expect(TestController).toBeDefined();
-    });
+      @ApiOperation({ summary: 'Get resource by ID' })
+      @ApiResponse(200, { description: 'Resource found' })
+      @ApiResponse(404, { description: 'Resource not found' })
+      @Get('/:id')
+      async get(@Param('id') id: string): Promise<Response> {
+        return this.success({ id });
+      }
+    }
+
+    expect(ResourceController).toBeDefined();
   });
 
-  describe('@ApiHeader options', () => {
-    it('should accept name and description', () => {
-      class TestController {
-        @ApiHeader({
-          name: 'X-Request-ID',
-          description: 'Request ID for tracing',
-        })
-        async testMethod() {}
+  it('should use @ApiTags for grouping', () => {
+    // Note: @ApiTags MUST be placed ABOVE @Controller
+    // because @Controller wraps the class and decorators apply bottom-to-top
+    @ApiTags('Users')
+    @Controller('/users')
+    class UsersController extends BaseController {
+      @Get('/')
+      async list(): Promise<Response> {
+        return this.success([]);
+      }
+    }
+
+    @ApiTags('Orders')
+    @Controller('/orders')
+    class OrdersController extends BaseController {
+      @Get('/')
+      async list(): Promise<Response> {
+        return this.success([]);
       }
+    }
+
+    const usersTags = getApiTagsMetadata(UsersController);
+    const ordersTags = getApiTagsMetadata(OrdersController);
+    
+    expect(usersTags).toBeDefined();
+    expect(usersTags).toContain('Users');
+    expect(ordersTags).toBeDefined();
+    expect(ordersTags).toContain('Orders');
+  });
 
-      expect(TestController).toBeDefined();
+  it('should document response types with @ApiResponse from core', () => {
+    const userSchema = type({
+      id: 'string',
+      name: 'string',
+      email: 'string.email',
     });
+
+    @Controller('/users')
+    class UserController extends BaseController {
+      @ApiResponse(200, { schema: userSchema, description: 'User found' })
+      @ApiResponse(404, { description: 'User not found' })
+      @Get('/:id')
+      async getUser(@Param('id') id: string): Promise<Response> {
+        return this.success({ id, name: 'Test', email: 'test@test.com' });
+      }
+    }
+
+    expect(UserController).toBeDefined();
   });
 });