bxo 0.0.5-dev.70 → 0.0.5-dev.72

package/README.md

@@ -93,6 +93,76 @@ app.use(cors({
 }));
 ```
 
+### OpenAPI Plugin
+
+The OpenAPI plugin automatically generates OpenAPI 3.0 documentation with support for tags, security schemes, and comprehensive route metadata:
+
+```typescript
+import { openapi } from "./plugins";
+
+app.use(openapi({
+  path: "/docs",                    // Swagger UI endpoint
+  jsonPath: "/openapi.json",        // OpenAPI JSON endpoint
+  defaultTags: ["API"],             // Default tags for routes
+  securitySchemes: {                // Define security schemes
+    bearerAuth: {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+      description: "JWT token for authentication"
+    },
+    apiKeyAuth: {
+      type: "apiKey",
+      in: "header",
+      name: "X-API-Key",
+      description: "API key for authentication"
+    }
+  },
+  globalSecurity: [                 // Global security requirements
+    { bearerAuth: [] },
+    { apiKeyAuth: [] }
+  ],
+  openapiConfig: {                  // Additional OpenAPI config
+    info: {
+      title: "My API",
+      version: "1.0.0",
+      description: "API description"
+    }
+  }
+}));
+```
+
+#### Route Metadata
+
+Routes can include detailed metadata for better OpenAPI documentation:
+
+```typescript
+app.get("/users/:id", (ctx) => {
+  const id = ctx.params.id
+  return { user: { id, name: "John Doe" } }
+}, {
+  detail: {
+    tags: ["Users"],                    // Route tags for grouping
+    summary: "Get user by ID",          // Operation summary
+    description: "Retrieve user details", // Detailed description
+    security: [{ bearerAuth: [] }],     // Route-specific security
+    params: {                           // Parameter documentation
+      id: z.string().describe("User ID")
+    }
+  }
+})
+```
+
+#### Supported Metadata Fields
+
+- `tags`: Array of tags for grouping operations
+- `summary`: Short description of the operation
+- `description`: Detailed description of the operation
+- `security`: Security requirements for the route
+- `params`: Path parameter schemas and descriptions
+- `query`: Query parameter schemas
+- `hidden`: Set to `true` to exclude from OpenAPI docs
+
 ### Creating Custom Plugins
 
 Plugins are just BXO instances with lifecycle hooks:
@@ -149,6 +219,7 @@ bun run ./example/cors-example.ts
 Check out the `example/` directory for more usage examples:
 
 - `cors-example.ts` - Demonstrates CORS plugin and lifecycle hooks
+- `openapi-example.ts` - Demonstrates OpenAPI plugin with tags and security
 - `index.ts` - Basic routing example
 
 This project was created using `bun init` in bun v1.2.3. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/example/index.ts

@@ -8,6 +8,7 @@ async function main() {
     bxo.default("/", index);
     bxo.default("/*", index);
 
+    // API routes with comprehensive metadata
     bxo.get("/api/get/:id", (ctx) => {
         return new Response(ctx.params.id + ctx.query.name, {
             headers: {
@@ -23,7 +24,16 @@ async function main() {
                 name: z.string()
             })
         },
+        detail: {
+            tags: ["API"],
+            summary: "Get data by ID",
+            description: "Retrieve data using an ID and name query parameter",
+            params: {
+                id: z.string().describe("Unique identifier for the data")
+            }
+        }
     });
+
     bxo.post("/api/post", (ctx) => {
         console.log(ctx.body)
         return new Response("Hello" + ctx.body.name, {
@@ -33,8 +43,10 @@ async function main() {
         });
     }, {
         detail: {
+            tags: ["API"],
+            summary: "Create new data",
+            description: "Submit new data with name and avatar file",
             defaultContentType: "multipart/form-data"
-
         },
         body: z.object({
             name: z.string(),
@@ -49,10 +61,131 @@ async function main() {
             })
         }
     });
-    bxo.use(openapi())
+
+    // Additional routes to showcase different features
+    bxo.get("/api/users", (ctx) => {
+        return ctx.json({ users: ["John", "Jane", "Bob"] });
+    }, {
+        detail: {
+            tags: ["Users"],
+            summary: "Get all users",
+            description: "Retrieve a list of all users in the system"
+        },
+        response: {
+            200: z.object({
+                users: z.array(z.string())
+            })
+        }
+    });
+
+    bxo.get("/api/users/:id", (ctx) => {
+        const id = ctx.params.id;
+        return ctx.json({ user: { id, name: "John Doe", email: "john@example.com" } });
+    }, {
+        detail: {
+            tags: ["Users"],
+            summary: "Get user by ID",
+            description: "Retrieve a specific user by their unique identifier",
+            params: {
+                id: z.string().describe("User's unique identifier")
+            }
+        },
+        response: {
+            200: z.object({
+                user: z.object({
+                    id: z.string(),
+                    name: z.string(),
+                    email: z.string()
+                })
+            }),
+            404: z.object({
+                error: z.string()
+            })
+        }
+    });
+
+    bxo.post("/api/users", (ctx) => {
+        const userData = ctx.body;
+        return ctx.json({ message: "User created", user: userData });
+    }, {
+        detail: {
+            tags: ["Users"],
+            summary: "Create new user",
+            description: "Create a new user account with the provided information"
+        },
+        body: z.object({
+            name: z.string().min(1, "Name is required"),
+            email: z.string().email("Invalid email format"),
+            age: z.number().min(18, "Must be at least 18 years old").optional()
+        }),
+        response: {
+            201: z.object({
+                message: z.string(),
+                user: z.object({
+                    name: z.string(),
+                    email: z.string(),
+                    age: z.number().optional()
+                })
+            }),
+            400: z.object({
+                error: z.string(),
+                issues: z.array(z.any()).optional()
+            })
+        }
+    });
+
+    // Health check route
+    bxo.get("/health", (ctx) => {
+        return ctx.json({ 
+            status: "ok", 
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime()
+        });
+    }, {
+        detail: {
+            tags: ["System"],
+            summary: "Health check",
+            description: "Check the health status of the API server"
+        },
+        response: {
+            200: z.object({
+                status: z.string(),
+                timestamp: z.string(),
+                uptime: z.number()
+            })
+        }
+    });
+
+    // Use OpenAPI plugin with enhanced configuration
+    bxo.use(openapi({
+        path: "/docs",
+        jsonPath: "/openapi.json",
+        defaultTags: ["API"],
+        securitySchemes: {
+            bearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "JWT",
+                description: "JWT token for authentication"
+            },
+            apiKeyAuth: {
+                type: "apiKey",
+                in: "header",
+                name: "X-API-Key",
+                description: "API key for authentication"
+            }
+        },
+        globalSecurity: [
+            { bearerAuth: [] },
+            { apiKeyAuth: [] }
+        ],
+        openapiConfig: {}
+    }));
+
     bxo.start();
     console.log(`Server is running on http://localhost:${bxo.server?.port}`);
-
+    console.log(`OpenAPI documentation available at http://localhost:${bxo.server?.port}/docs`);
+    console.log(`OpenAPI JSON available at http://localhost:${bxo.server?.port}/openapi.json`);
 }
 
 main();

package/example/openapi-example.ts

@@ -0,0 +1,132 @@
+import BXO, { z } from "../src";
+import { openapi } from "../plugins/openapi";
+
+// Create a BXO app with OpenAPI plugin
+const app = new BXO()
+    .use(openapi({
+        path: "/docs",
+        jsonPath: "/openapi.json",
+        defaultTags: ["API"],
+        securitySchemes: {
+            bearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "JWT",
+                description: "JWT token for authentication"
+            },
+            apiKeyAuth: {
+                type: "apiKey",
+                in: "header",
+                name: "X-API-Key",
+                description: "API key for authentication"
+            }
+        },
+        globalSecurity: [
+            { bearerAuth: [] },
+            { apiKeyAuth: [] }
+        ],
+        openapiConfig: {
+            info: {
+                title: "My API with Security",
+                version: "1.0.0",
+                description: "An example API with OpenAPI documentation, tags, and security"
+            }
+        }
+    }))
+
+// Example routes with tags and security
+app.get("/users", (ctx) => {
+    return { users: [] }
+}, {
+    detail: {
+        tags: ["Users"],
+        summary: "Get all users",
+        description: "Retrieve a list of all users",
+        security: [{ bearerAuth: [] }]
+    }
+})
+
+app.get("/users/:id", (ctx) => {
+    const id = ctx.params.id
+    return { user: { id, name: "John Doe" } }
+}, {
+    detail: {
+        tags: ["Users"],
+        summary: "Get user by ID",
+        description: "Retrieve a specific user by their ID",
+        params: {
+            id: z.string().describe("User ID")
+        },
+        security: [{ apiKeyAuth: [] }]
+    }
+})
+
+app.post("/users", (ctx) => {
+    const body = ctx.body
+    return { message: "User created", user: body }
+}, {
+    body: z.object({
+        name: z.string(),
+        email: z.string().email()
+    }),
+    detail: {
+        tags: ["Users"],
+        summary: "Create a new user",
+        description: "Create a new user with the provided information",
+        security: [{ bearerAuth: [] }]
+    }
+})
+
+app.get("/products", (ctx) => {
+    return { products: [] }
+}, {
+    detail: {
+        tags: ["Products"],
+        summary: "Get all products",
+        description: "Retrieve a list of all products"
+    }
+})
+
+app.get("/products/:id", (ctx) => {
+    const id = ctx.params.id
+    return { product: { id, name: "Sample Product" } }
+}, {
+    detail: {
+        tags: ["Products"],
+        summary: "Get product by ID",
+        description: "Retrieve a specific product by its ID",
+        params: {
+            id: z.string().describe("Product ID")
+        }
+    }
+})
+
+// Admin routes with different security
+app.get("/admin/users", (ctx) => {
+    return { adminUsers: [] }
+}, {
+    detail: {
+        tags: ["Admin"],
+        summary: "Get all users (Admin)",
+        description: "Admin-only endpoint to retrieve all users",
+        security: [{ bearerAuth: [] }, { apiKeyAuth: [] }]
+    }
+})
+
+// Health check route (no security required)
+app.get("/health", (ctx) => {
+    return { status: "ok", timestamp: new Date().toISOString() }
+}, {
+    detail: {
+        tags: ["System"],
+        summary: "Health check",
+        description: "Check if the API is running"
+    }
+})
+
+// Start the server
+app.listen(3000, () => {
+    console.log("Server running on http://localhost:3000")
+    console.log("OpenAPI docs available at http://localhost:3000/docs")
+    console.log("OpenAPI JSON available at http://localhost:3000/openapi.json")
+})

package/package.json

@@ -5,7 +5,7 @@
     ".": "./src/index.ts",
     "./plugins": "./plugins/index.ts"
   },
-  "version": "0.0.5-dev.70",
+  "version": "0.0.5-dev.72",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"

package/plugins/openapi.ts

@@ -1,14 +1,22 @@
 import BXO, { z } from "../src";
-import { createDocument, type CreateDocumentOptions, type ZodOpenApiPathsObject } from "zod-openapi";
-
-class OpenApiConfig {
+import { createDocument, type CreateDocumentOptions, type ZodOpenApiPathItemObject, type ZodOpenApiPathsObject, type ZodOpenApiSecuritySchemeObject } from "zod-openapi";
 
+interface SecurityScheme extends ZodOpenApiSecuritySchemeObject {
+    type: "http" | "apiKey" | "oauth2" | "openIdConnect";
+    scheme?: "bearer" | "basic" | "digest" | "apikey";
+    bearerFormat?: string;
+    description?: string;
+    name?: string;
+    in?: "header" | "query" | "cookie";
 }
 
 interface OpenApiPluginConfig {
     path: string;
     jsonPath: string;
     openapiConfig: CreateDocumentOptions;
+    defaultTags?: string[];
+    securitySchemes?: Record<string, SecurityScheme>;
+    globalSecurity?: Array<Record<string, string[]>>;
 }
 
 const createOpenApiPaths = (app: BXO, config?: OpenApiPluginConfig): ZodOpenApiPathsObject => {
@@ -30,6 +38,60 @@ const createOpenApiPaths = (app: BXO, config?: OpenApiPluginConfig): ZodOpenApiP
         if (route.schema?.detail?.hidden) {
             continue
         }
+
+        // Extract tags from route metadata
+        const tags = route.schema?.detail?.tags ||
+            route.schema?.detail?.tag ||
+            config?.defaultTags ||
+            []
+
+        // Extract security requirements from route metadata
+        const routeSecurity = route.schema?.detail?.security ||
+            route.schema?.detail?.auth ||
+            undefined
+
+        // Extract operation summary and description
+        const summary = route.schema?.detail?.summary ||
+            route.schema?.detail?.title ||
+            `${method.toUpperCase()} ${route.path}`
+
+        const description = route.schema?.detail?.description ||
+            route.schema?.detail?.docs ||
+            undefined
+
+        // Extract parameters from route path
+        const parameters = []
+        const pathParams = route.path.match(/:\w+/g)
+        if (pathParams) {
+            for (const param of pathParams) {
+                const paramName = param.slice(1) // Remove the colon
+                const paramSchema = route.schema?.detail?.params?.[paramName] || z.string()
+                parameters.push({
+                    name: paramName,
+                    in: "path",
+                    required: true,
+                    schema: paramSchema
+                })
+            }
+        }
+
+        // Add query parameters if defined
+        if (route.schema?.query) {
+            const querySchema = route.schema?.query
+            if (querySchema && typeof querySchema === 'object' && 'shape' in querySchema) {
+                const queryShape = (querySchema as any).shape
+                for (const [key, schema] of Object.entries(queryShape)) {
+                    const isOptional = schema instanceof z.ZodOptional
+                    parameters.push({
+                        name: key,
+                        in: "query",
+                        required: !isOptional, // Query params are typically optional
+                        schema: schema as any
+                    })
+                }
+            }
+        }
+
         const response = Object.entries(route.schema?.response || {}).map(([status, schema]) => {
             return ({
                 400: status === "400" && !route.schema?.response?.[status] ? {
@@ -51,9 +113,15 @@ const createOpenApiPaths = (app: BXO, config?: OpenApiPluginConfig): ZodOpenApiP
                 }
             })
         }).reduce((acc, curr) => ({ ...acc, ...curr }), {})
+
         paths[openapiPath] = {
             ...paths[openapiPath],
             [method]: {
+                tags: tags.length > 0 ? tags : undefined,
+                summary: summary,
+                description: description,
+                parameters: parameters.length > 0 ? parameters : undefined,
+                security: routeSecurity,
                 requestBody: {
                     content: {
                         [contentType]: {
@@ -71,18 +139,20 @@ const createOpenApiPaths = (app: BXO, config?: OpenApiPluginConfig): ZodOpenApiP
                     }
                 }
             }
-        }
+        } satisfies ZodOpenApiPathItemObject
     }
     return paths
 }
 
 export function openapi(_config?: OpenApiPluginConfig) {
     let config = _config
-    !config && (config = { path: "/docs", openapiConfig: new OpenApiConfig(), jsonPath: "/openapi.json" })
+    !config && (config = { path: "/docs", openapiConfig: {}, jsonPath: "/openapi.json" })
     config.path = config.path || "/docs"
     config.jsonPath = config.jsonPath || "/openapi.json"
     config.openapiConfig = config.openapiConfig || {}
-
+    config.defaultTags = config.defaultTags || []
+    config.securitySchemes = config.securitySchemes || {}
+    config.globalSecurity = config.globalSecurity || []
 
     const bxo = new BXO()
         .get(config.jsonPath, (ctx, app) => {
@@ -93,6 +163,10 @@ export function openapi(_config?: OpenApiPluginConfig) {
                     version: "1.0.0"
                 },
                 paths: createOpenApiPaths(app, config),
+                components: {
+                    securitySchemes: Object.keys(config.securitySchemes || {}).length > 0 ? config.securitySchemes : undefined
+                },
+                security: (config.globalSecurity || []).length > 0 ? config.globalSecurity : undefined,
                 ...config.openapiConfig
             })
             return new Response(JSON.stringify(paths), {