@davaux/swagger 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/swagger
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.470Z
+
+## Overview
+
+Auto-generated OpenAPI/Swagger documentation for Davaux APIs
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`swagger`, `SwaggerInfo`, `SwaggerOptions`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @davaux/swagger
+
+Auto-generated OpenAPI/Swagger documentation for Davaux APIs.
+
+## Installation
+
+```bash
+npm install @davaux/swagger
+```
+
+## Setup
+
+Mount as middleware in a route file or middleware:
+
+```ts
+// src/routes/api/_middleware.ts
+import { swagger } from '@davaux/swagger'
+
+export default swagger({
+  routesDir: './dist/routes',
+  info: { title: 'My API', version: '1.0.0' },
+})
+```
+
+This serves:
+- **`/docs`** — Swagger UI
+- **`/openapi.json`** — raw OpenAPI 3.0 spec
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `routesDir` | `string` | — | Directory of compiled route files to introspect (required) |
+| `info.title` | `string` | `'API'` | API title |
+| `info.version` | `string` | `'1.0.0'` | API version |
+| `info.description` | `string` | — | API description |
+| `path` | `string` | `'/docs'` | URL path for the Swagger UI page |
+| `specPath` | `string` | `'/openapi.json'` | URL path for the raw OpenAPI JSON |
+
+## Automatic request body documentation
+
+When `zod-to-json-schema` is installed, mutating routes that export a `*Schema` named export have their request body documented automatically:
+
+```ts
+// src/routes/api/users.post.ts
+import { z } from 'zod'
+
+export const userSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+})
+
+export default defineHandler(async (ctx) => { ... })
+```
+
+## Notes
+
+- The spec is generated once on the first request and cached for the process lifetime
+- `page` routes (HTML pages) are excluded; only API handler files appear in the spec
+- In single-site dev, point `routesDir` at `.davaux/routes` — the dev server's compiled output. For `@davaux/multisite` dev, use `.davaux-multisite/routes`
+
+## Documentation
+
+[davaux.codeberg.page/docs/swagger](https://davaux.codeberg.page/docs/swagger)

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@davaux/swagger",
+  "version": "0.8.0",
+  "description": "Auto-generated OpenAPI/Swagger documentation for Davaux APIs",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0"
+  },
+  "peerDependenciesMetadata": {
+    "zod-to-json-schema": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,205 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { MiddlewareFn } from 'davaux'
+
+/** OpenAPI metadata used in the `info` block of the generated spec. */
+export interface SwaggerInfo {
+  title?: string
+  version?: string
+  description?: string
+}
+
+export interface SwaggerOptions {
+  /**
+   * Directory containing compiled route files to introspect.
+   * In production: the davaux build output directory (default: './dist').
+   * In development: './.davaux/routes' (the dev server's compiled output).
+   */
+  routesDir: string
+  /** OpenAPI info block. */
+  info?: SwaggerInfo
+  /** URL path for the Swagger UI page. Default: '/docs' */
+  path?: string
+  /** URL path for the raw OpenAPI JSON spec. Default: '/openapi.json' */
+  specPath?: string
+}
+
+const TYPE_TO_METHOD: Record<string, string | undefined> = {
+  get: 'get',
+  post: 'post',
+  put: 'put',
+  patch: 'patch',
+  delete: 'delete',
+  head: 'head',
+  options: 'options',
+  page: undefined, // HTML page routes are not API endpoints
+}
+
+function toOpenApiPath(pattern: string): string {
+  return pattern
+    .replace(/:(\w+)/g, '{$1}') // :id → {id}
+    .replace(/\*(\w+)/g, '{$1}') // *slug → {slug} (catch-all)
+}
+
+function buildInfo(info?: SwaggerInfo): object {
+  return {
+    title: info?.title ?? 'API',
+    version: info?.version ?? '1.0.0',
+    ...(info?.description ? { description: info.description } : {}),
+  }
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function swaggerHtml(specPath: string, title: string): string {
+  return `<!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://cdn.jsdelivr.net/npm/swagger-ui-dist@5.18.2/swagger-ui.css" integrity="sha384-rcbEi6xgdPk0iWkAQzT2F3FeBJXdG+ydrawGlfHAFIZG7wU6aKbQaRewysYpmrlW" crossorigin="anonymous" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.18.2/swagger-ui-bundle.js" integrity="sha384-NXtFPpN61oWCuN4D42K6Zd5Rt2+uxeIT36R7kpXBuY9tLnZorzrJ4ykpqwJfgjpZ" crossorigin="anonymous"></script>
+<script>
+window.onload = () => {
+  SwaggerUIBundle({
+    url: ${JSON.stringify(specPath)},
+    dom_id: '#swagger-ui',
+    presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+    layout: 'StandaloneLayout',
+    deepLinking: true,
+  })
+}
+</script>
+</body>
+</html>`
+}
+
+async function buildSpec(options: SwaggerOptions): Promise<object> {
+  const routesDir = resolve(options.routesDir)
+
+  if (!existsSync(routesDir)) {
+    console.warn(`[@davaux/swagger] routesDir not found: ${routesDir} — serving empty spec`)
+    return { openapi: '3.0.0', info: buildInfo(options.info), paths: {} }
+  }
+
+  const { scanRoutes } = await import('davaux/scanner')
+  const { routes } = await scanRoutes(routesDir)
+
+  const paths: Record<string, Record<string, unknown>> = {}
+
+  for (const route of routes) {
+    const method = TYPE_TO_METHOD[route.type]
+    if (!method) continue
+
+    const openApiPath = toOpenApiPath(route.urlPattern)
+    if (!paths[openApiPath]) paths[openApiPath] = {}
+
+    const parameters = route.params.map((param) => ({
+      name: param,
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    }))
+
+    const operation: Record<string, unknown> = {
+      parameters,
+      responses: {
+        '200': { description: 'Success' },
+        '400': { description: 'Bad Request' },
+        '500': { description: 'Internal Server Error' },
+      },
+    }
+
+    // For mutating methods, try to extract the first named *Schema export from the
+    // compiled route module and convert it to a JSON Schema request body.
+    // Requires zod-to-json-schema to be installed — silently skipped otherwise.
+    if (method !== 'get' && method !== 'head' && method !== 'options') {
+      try {
+        const mod = (await import(route.filePath)) as Record<string, unknown>
+        const schemaEntry = Object.entries(mod).find(([k]) => k.endsWith('Schema'))
+        if (schemaEntry) {
+          // Dynamic import by variable so TypeScript doesn't statically resolve
+          // the optional peer dep (zod-to-json-schema may not be installed).
+          const depId = 'zod-to-json-schema'
+          const ztjs = (await import(depId)) as {
+            zodToJsonSchema: (schema: unknown, opts?: { target: string }) => unknown
+          }
+          operation.requestBody = {
+            required: true,
+            content: {
+              'application/json': {
+                schema: ztjs.zodToJsonSchema(schemaEntry[1], { target: 'openapi3' }),
+              },
+            },
+          }
+        }
+      } catch {
+        // zod-to-json-schema not installed or module import failed — skip
+      }
+    }
+
+    paths[openApiPath][method] = operation
+  }
+
+  return {
+    openapi: '3.0.0',
+    info: buildInfo(options.info),
+    paths,
+  }
+}
+
+/**
+ * OpenAPI/Swagger middleware. Introspects compiled route files to build an
+ * OpenAPI 3.0 spec and serves it at `specPath` (default: `/openapi.json`),
+ * plus a Swagger UI page at `path` (default: `/docs`).
+ *
+ * The spec is generated once on the first request and cached for the lifetime
+ * of the process. When `zod-to-json-schema` is installed, mutating routes that
+ * export a `*Schema` named export will have their request body documented
+ * automatically.
+ *
+ * @example
+ * import { swagger } from '@davaux/swagger'
+ * export default swagger({
+ *   routesDir: './dist/routes',
+ *   info: { title: 'My API', version: '1.0.0' },
+ * })
+ */
+export function swagger(options: SwaggerOptions): MiddlewareFn {
+  const docsPath = options.path ?? '/docs'
+  const specPath = options.specPath ?? '/openapi.json'
+  const title = options.info?.title ?? 'API Docs'
+
+  // Spec is generated once on the first request and cached for the process lifetime.
+  let specPromise: Promise<object> | null = null
+
+  return async (ctx, next) => {
+    const pathname = ctx.req.url?.split('?')[0] ?? '/'
+
+    if (pathname === specPath) {
+      if (!specPromise) specPromise = buildSpec(options)
+      const spec = await specPromise
+      ctx.res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' })
+      ctx.res.end(JSON.stringify(spec, null, 2))
+      return
+    }
+
+    if (pathname === docsPath) {
+      ctx.res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      ctx.res.end(swaggerHtml(specPath, title))
+      return
+    }
+
+    return next()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}