@veloxts/router 0.6.57 → 0.6.59

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 0.6.59
+
+### Patch Changes
+
+- refactor(ecosystem): Laravel-style API refinements & added missing unit tests
+- Updated dependencies
+  - @veloxts/core@0.6.59
+  - @veloxts/validation@0.6.59
+
+## 0.6.58
+
+### Patch Changes
+
+- feat(router): add OpenAPI 3.0.3 specification generator
+- Updated dependencies
+  - @veloxts/core@0.6.58
+  - @veloxts/validation@0.6.58
+
 ## 0.6.57
 
 ### Patch Changes

package/GUIDE.md

@@ -72,6 +72,243 @@ await registerTRPCPlugin(app.server, { router, prefix: '/trpc' });
 export type AppRouter = typeof router;
 ```
 
+## OpenAPI Documentation
+
+Auto-generate OpenAPI 3.0.3 specifications from your procedure definitions and serve interactive Swagger UI documentation.
+
+### Generating OpenAPI Specs
+
+```typescript
+import { generateOpenApiSpec } from '@veloxts/router';
+
+const spec = generateOpenApiSpec([userProcedures, postProcedures], {
+  info: {
+    title: 'My API',
+    version: '1.0.0',
+    description: 'A VeloxTS-powered API',
+  },
+  prefix: '/api',
+  servers: [
+    { url: 'http://localhost:3030', description: 'Development' },
+    { url: 'https://api.example.com', description: 'Production' },
+  ],
+});
+
+// Write to file
+import fs from 'fs';
+fs.writeFileSync('openapi.json', JSON.stringify(spec, null, 2));
+```
+
+### Swagger UI Plugin
+
+Serve interactive API documentation with Swagger UI:
+
+```typescript
+import { swaggerUIPlugin } from '@veloxts/router';
+
+app.server.register(swaggerUIPlugin, {
+  routePrefix: '/docs',
+  collections: [userProcedures, postProcedures],
+  openapi: {
+    info: { title: 'My API', version: '1.0.0' },
+    prefix: '/api',
+  },
+  title: 'API Documentation',
+});
+
+// Available at:
+// - /docs - Swagger UI interface
+// - /docs/openapi.json - Raw OpenAPI spec
+```
+
+### Factory Functions
+
+```typescript
+import { createSwaggerUI, getOpenApiSpec, registerDocs } from '@veloxts/router';
+
+// Create pre-configured plugin
+const docs = createSwaggerUI({
+  collections: [userProcedures],
+  openapi: { info: { title: 'My API', version: '1.0.0' } },
+});
+app.server.register(docs);
+
+// Get spec without registering routes
+const spec = getOpenApiSpec({
+  collections: [userProcedures],
+  openapi: { info: { title: 'My API', version: '1.0.0' } },
+});
+
+// Register docs with one call
+await registerDocs(app.server, {
+  collections: [userProcedures],
+  openapi: { info: { title: 'My API', version: '1.0.0' } },
+});
+```
+
+### CLI Command
+
+Generate OpenAPI specs from the command line:
+
+```bash
+# Basic generation
+velox openapi generate --output ./openapi.json
+
+# Full options
+velox openapi generate \
+  --path ./src/procedures \
+  --output ./docs/openapi.json \
+  --title "My API" \
+  --version "1.0.0" \
+  --description "API documentation" \
+  --server http://localhost:3030 \
+  --server https://api.example.com \
+  --prefix /api
+
+# Serve documentation locally
+velox openapi serve --port 8080
+```
+
+### Security Schemes
+
+Guards are automatically mapped to OpenAPI security requirements:
+
+```typescript
+import { procedure, authenticated, hasRole } from '@veloxts/router';
+
+const adminProcedures = procedures('admin', {
+  // 'authenticated' guard → bearerAuth security
+  listStats: procedure()
+    .guard(authenticated)
+    .query(handler),
+
+  // 'hasRole:admin' guard → bearerAuth security
+  deleteUser: procedure()
+    .input(z.object({ id: z.string().uuid() }))
+    .guard(hasRole('admin'))
+    .mutation(handler),
+});
+```
+
+Default guard mappings:
+
+| Guard Name | Security Scheme |
+|------------|-----------------|
+| `authenticated` | `bearerAuth` |
+| `hasRole:*` | `bearerAuth` |
+| `hasPermission:*` | `bearerAuth` |
+| `apiKey` | `apiKeyAuth` |
+
+Custom security mappings:
+
+```typescript
+const spec = generateOpenApiSpec([procedures], {
+  info: { title: 'API', version: '1.0.0' },
+  guardToSecurityMap: {
+    'custom-guard': 'oauth2',
+    'internal-only': 'apiKeyAuth',
+  },
+  securitySchemes: {
+    oauth2: {
+      type: 'oauth2',
+      flows: {
+        authorizationCode: {
+          authorizationUrl: 'https://auth.example.com/authorize',
+          tokenUrl: 'https://auth.example.com/token',
+          scopes: { read: 'Read access', write: 'Write access' },
+        },
+      },
+    },
+  },
+});
+```
+
+### Generator Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `info` | `OpenAPIInfo` | required | API title, version, description |
+| `prefix` | `string` | `'/api'` | Base path for all routes |
+| `servers` | `OpenAPIServer[]` | `[]` | Server URLs |
+| `tagDescriptions` | `Record<string, string>` | `{}` | Descriptions for namespace tags |
+| `securitySchemes` | `Record<string, SecurityScheme>` | defaults | Custom security schemes |
+| `guardToSecurityMap` | `Record<string, string>` | defaults | Guard → scheme mapping |
+| `defaultSecurity` | `SecurityRequirement[]` | `[]` | Global security requirements |
+| `externalDocs` | `ExternalDocs` | `undefined` | Link to external docs |
+| `extensions` | `Record<string, unknown>` | `{}` | OpenAPI extensions (`x-*`) |
+
+### Swagger UI Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `routePrefix` | `string` | `'/docs'` | UI route path |
+| `specRoute` | `string` | `'{prefix}/openapi.json'` | Spec JSON path |
+| `title` | `string` | `'API Documentation'` | Page title |
+| `favicon` | `string` | `undefined` | Favicon URL |
+| `uiConfig.deepLinking` | `boolean` | `true` | Enable deep linking |
+| `uiConfig.tryItOutEnabled` | `boolean` | `true` | Enable "Try it out" |
+| `uiConfig.persistAuthorization` | `boolean` | `false` | Persist auth in localStorage |
+| `uiConfig.docExpansion` | `string` | `'list'` | `'list'`, `'full'`, `'none'` |
+
+### Schema Conversion
+
+Zod schemas are automatically converted to JSON Schema:
+
+```typescript
+// Input
+z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  age: z.number().min(0).max(150).optional(),
+})
+
+// Output (JSON Schema)
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "email": { "type": "string", "format": "email" },
+    "age": { "type": "number", "minimum": 0, "maximum": 150 }
+  },
+  "required": ["id", "email"]
+}
+```
+
+### Validation
+
+Validate generated specs for common issues:
+
+```typescript
+import { validateOpenApiSpec } from '@veloxts/router';
+
+const spec = generateOpenApiSpec([procedures], options);
+const warnings = validateOpenApiSpec(spec);
+
+if (warnings.length > 0) {
+  console.warn('OpenAPI warnings:', warnings);
+}
+// Possible warnings:
+// - "OpenAPI spec has no paths defined"
+// - "OpenAPI spec is missing info.title"
+// - "Duplicate operationId: users_getUser"
+```
+
+### Route Summary
+
+Get a summary of generated routes for debugging:
+
+```typescript
+import { getOpenApiRouteSummary } from '@veloxts/router';
+
+const routes = getOpenApiRouteSummary([userProcedures], '/api');
+console.table(routes);
+// [
+//   { method: 'GET', path: '/api/users/{id}', operationId: 'users_getUser', namespace: 'users' },
+//   { method: 'GET', path: '/api/users', operationId: 'users_listUsers', namespace: 'users' },
+//   { method: 'POST', path: '/api/users', operationId: 'users_createUser', namespace: 'users' },
+// ]
+```
+
 ## Middleware
 
 ```typescript

package/dist/index.d.ts

@@ -81,3 +81,25 @@ export { serve } from './expose.js';
 export { appRouterProvider, registerRouterProviders, trpcInstanceProvider, trpcPluginOptionsProvider, } from './providers.js';
 export type { RestAdapterConfig, RouterConfig } from './tokens.js';
 export { APP_ROUTER, PROCEDURE_COLLECTIONS, REST_ADAPTER_CONFIG, ROUTER_CONFIG, TRPC_INSTANCE, TRPC_PLUGIN_OPTIONS, } from './tokens.js';
+/**
+ * OpenAPI 3.0.3 specification generation from procedure collections.
+ *
+ * @example
+ * ```typescript
+ * import { generateOpenApiSpec, swaggerUIPlugin } from '@veloxts/router';
+ *
+ * // Generate spec programmatically
+ * const spec = generateOpenApiSpec([userProcedures], {
+ *   info: { title: 'My API', version: '1.0.0' },
+ * });
+ *
+ * // Or serve Swagger UI
+ * app.register(swaggerUIPlugin, {
+ *   routePrefix: '/docs',
+ *   collections: [userProcedures],
+ *   openapi: { info: { title: 'My API', version: '1.0.0' } },
+ * });
+ * ```
+ */
+export type { BuildParametersOptions, BuildParametersResult, GuardMappingOptions, JSONSchema, OpenAPIComponents, OpenAPIContact, OpenAPIEncoding, OpenAPIExample, OpenAPIExternalDocs, OpenAPIGeneratorOptions, OpenAPIHeader, OpenAPIHttpMethod, OpenAPIInfo, OpenAPILicense, OpenAPILink, OpenAPIMediaType, OpenAPIOAuthFlow, OpenAPIOAuthFlows, OpenAPIOperation, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPISpec, OpenAPITag, ParameterIn, QueryParamExtractionOptions, RouteInfo, SchemaConversionOptions, SecuritySchemeType, SwaggerUIConfig, SwaggerUIPluginOptions, } from './openapi/index.js';
+export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';

package/dist/index.js

@@ -86,3 +86,14 @@ export { serve } from './expose.js';
 // Provider exports - factory functions for registering services
 export { appRouterProvider, registerRouterProviders, trpcInstanceProvider, trpcPluginOptionsProvider, } from './providers.js';
 export { APP_ROUTER, PROCEDURE_COLLECTIONS, REST_ADAPTER_CONFIG, ROUTER_CONFIG, TRPC_INSTANCE, TRPC_PLUGIN_OPTIONS, } from './tokens.js';
+export { 
+// Path extractor
+buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, 
+// Security mapper
+createSecurityRequirement, 
+// Schema converter
+createStringSchema, 
+// Plugin
+createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
+// Generator
+generateOpenApiSpec, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';

package/dist/openapi/generator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenAPI Generator
+ *
+ * Generates OpenAPI 3.0.3 specifications from VeloxTS procedure collections.
+ *
+ * @module @veloxts/router/openapi/generator
+ */
+import type { ProcedureCollection } from '../types.js';
+import type { OpenAPIGeneratorOptions, OpenAPISpec } from './types.js';
+/**
+ * Generates an OpenAPI 3.0.3 specification from procedure collections
+ *
+ * @param collections - Array of procedure collections to document
+ * @param options - Generator options
+ * @returns Complete OpenAPI specification
+ *
+ * @example
+ * ```typescript
+ * import { generateOpenApiSpec } from '@veloxts/router';
+ *
+ * const spec = generateOpenApiSpec([userProcedures, postProcedures], {
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'A VeloxTS-powered API',
+ *   },
+ *   prefix: '/api',
+ *   servers: [{ url: 'http://localhost:3030' }],
+ * });
+ * ```
+ */
+export declare function generateOpenApiSpec(collections: ProcedureCollection[], options: OpenAPIGeneratorOptions): OpenAPISpec;
+/**
+ * Gets route summary information for debugging/logging
+ *
+ * @param collections - Procedure collections
+ * @param prefix - API prefix
+ * @returns Array of route summaries
+ */
+export declare function getOpenApiRouteSummary(collections: ProcedureCollection[], prefix?: string): Array<{
+    method: string;
+    path: string;
+    operationId: string;
+    namespace: string;
+}>;
+/**
+ * Validates an OpenAPI spec for common issues
+ *
+ * @param spec - OpenAPI spec to validate
+ * @returns Array of validation warnings
+ */
+export declare function validateOpenApiSpec(spec: OpenAPISpec): string[];