139 lines
4.0 KiB
TypeScript
139 lines
4.0 KiB
TypeScript
/**
|
|
* Request handlers for OpenAPI specification and Swagger UI
|
|
*/
|
|
|
|
import type { IRequestContext } from '../core/smartserve.interfaces.js';
|
|
import { OpenApiGenerator } from './openapi.generator.js';
|
|
import type { IOpenApiGeneratorOptions } from './openapi.types.js';
|
|
|
|
/**
|
|
* Create a handler that serves the OpenAPI JSON specification
|
|
*/
|
|
export function createOpenApiHandler(options: IOpenApiGeneratorOptions) {
|
|
let cachedSpec: string | null = null;
|
|
|
|
return async (ctx: IRequestContext): Promise<Response> => {
|
|
// Generate spec on first request (lazy loading)
|
|
if (!cachedSpec) {
|
|
const generator = new OpenApiGenerator(options);
|
|
cachedSpec = generator.toJSON();
|
|
}
|
|
|
|
return new Response(cachedSpec, {
|
|
status: 200,
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'Cache-Control': 'public, max-age=3600',
|
|
},
|
|
});
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Create a handler that serves Swagger UI
|
|
*
|
|
* Loads Swagger UI from unpkg CDN - no bundled assets needed
|
|
*/
|
|
export function createSwaggerUiHandler(specUrl: string = '/openapi.json', title: string = 'API Documentation') {
|
|
const html = `<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<title>${escapeHtml(title)}</title>
|
|
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
|
|
<style>
|
|
html { box-sizing: border-box; overflow-y: scroll; }
|
|
*, *:before, *:after { box-sizing: inherit; }
|
|
body { margin: 0; background: #fafafa; }
|
|
.swagger-ui .topbar { display: none; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div id="swagger-ui"></div>
|
|
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
|
|
<script>
|
|
window.onload = () => {
|
|
window.ui = SwaggerUIBundle({
|
|
url: "${escapeHtml(specUrl)}",
|
|
dom_id: '#swagger-ui',
|
|
deepLinking: true,
|
|
presets: [
|
|
SwaggerUIBundle.presets.apis,
|
|
SwaggerUIBundle.SwaggerUIStandalonePreset
|
|
],
|
|
plugins: [
|
|
SwaggerUIBundle.plugins.DownloadUrl
|
|
],
|
|
layout: "BaseLayout",
|
|
validatorUrl: null,
|
|
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'],
|
|
defaultModelsExpandDepth: 1,
|
|
defaultModelExpandDepth: 1,
|
|
displayRequestDuration: true,
|
|
filter: true,
|
|
showExtensions: true,
|
|
showCommonExtensions: true,
|
|
});
|
|
};
|
|
</script>
|
|
</body>
|
|
</html>`;
|
|
|
|
return async (ctx: IRequestContext): Promise<Response> => {
|
|
return new Response(html, {
|
|
status: 200,
|
|
headers: {
|
|
'Content-Type': 'text/html; charset=utf-8',
|
|
'Cache-Control': 'public, max-age=86400',
|
|
},
|
|
});
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Create a handler that serves ReDoc UI (alternative to Swagger UI)
|
|
*
|
|
* ReDoc provides a clean, responsive documentation layout
|
|
*/
|
|
export function createReDocHandler(specUrl: string = '/openapi.json', title: string = 'API Documentation') {
|
|
const html = `<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<title>${escapeHtml(title)}</title>
|
|
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
<style>
|
|
body { margin: 0; padding: 0; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<redoc spec-url="${escapeHtml(specUrl)}"></redoc>
|
|
<script src="https://unpkg.com/redoc@latest/bundles/redoc.standalone.js"></script>
|
|
</body>
|
|
</html>`;
|
|
|
|
return async (ctx: IRequestContext): Promise<Response> => {
|
|
return new Response(html, {
|
|
status: 200,
|
|
headers: {
|
|
'Content-Type': 'text/html; charset=utf-8',
|
|
'Cache-Control': 'public, max-age=86400',
|
|
},
|
|
});
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Escape HTML special characters to prevent XSS
|
|
*/
|
|
function escapeHtml(str: string): string {
|
|
return str
|
|
.replace(/&/g, '&')
|
|
.replace(/</g, '<')
|
|
.replace(/>/g, '>')
|
|
.replace(/"/g, '"')
|
|
.replace(/'/g, ''');
|
|
}
|