prisma-swagger-autogen 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 QUIKK Software GmbH / Joyce Marvin Rafflenbeul
+
+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,264 @@
+# Prisma Swagger Autogen
+
+Generate a **fully typed OpenAPI 3 specification directly from your Prisma models** and use it seamlessly with **`swagger-autogen`**.
+
+This package allows you to treat **Prisma as the single source of truth** for your API data structures and automatically expose those structures as **correct Swagger schemas**, without manually duplicating DTOs or schema definitions.
+
+---
+
+## ✨ What This Tool Is For
+
+The main goal of this package is:
+
+> **To automatically generate correct Swagger/OpenAPI schemas based on your Prisma models, so that Swagger, Swagger UI, and generated API clients all share the same types.**
+
+Instead of:
+- manually writing OpenAPI schemas
+- duplicating DTOs
+- maintaining separate validation and documentation layers
+
+you can rely on **Prisma’s type system** and generate everything from there.
+
+---
+
+## 🔁 How It Fits Into Your Tooling
+
+This tool is designed to work **together with `swagger-autogen`**, not replace it.
+
+### The workflow looks like this:
+
+1. **Prisma models** define your domain
+2. This package:
+    - reads Prisma DMMF
+    - generates OpenAPI schemas (`components.schemas`)
+    - builds a ready-to-use `swagger.config.js`
+3. **`swagger-autogen`**:
+    - scans your controllers
+    - uses the generated config
+    - produces a complete `openapi.json`
+4. Optional:
+    - generate a TypeScript client
+    - generate SDKs
+    - use Swagger UI
+
+✔ One source of truth  
+✔ No duplicated schemas  
+✔ No mismatched DTOs
+
+---
+
+## 🚀 Why This Matters
+
+Without this approach, teams often end up with:
+
+- Prisma models
+- Request/Response DTOs
+- Swagger schemas
+- Client-side models
+
+…all slightly different.
+
+This tool ensures that:
+
+- **Prisma → Swagger is automatic**
+- **Swagger schemas are structurally correct**
+- **Swagger-generated TypeScript clients contain real data shapes**
+- **Request bodies and responses are usable out of the box**
+
+---
+
+## ❌ What This Tool Does *Not* Do
+
+- It does **not** replace `swagger-autogen`
+- It does **not** scan controllers itself
+- It does **not** generate routes
+
+Instead, it **prepares the Swagger configuration** so that `swagger-autogen` can do its job properly.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -D prisma-swagger-autogen
+```
+
+---
+
+## 🛠 Usage
+
+1. Generate swagger.config.js from Prisma
+
+``` 
+npx prisma-swagger-autogen
+```
+
+This will generate a swagger.config.js file in your project root.
+
+The file already contains:
+
+- components.schemas derived from Prisma
+- security schemes
+- server configuration
+- controller file paths
+
+2. Run swagger-autogen
+ 
+```
+node swagger.config.js
+```
+
+This generates:
+
+`src/web/api/openapi.json`
+
+3. (Optional) Generate a TypeScript API client
+   
+```
+npx swagger-typescript-api \
+   -p src/web/api/openapi.json \
+   -o src/web/api/client \
+   -n api.ts
+```
+
+
+The resulting TypeScript types now match your Prisma models:
+
+```typescript
+export interface GetUserResponse {
+    userId: string;
+    name: string;
+    birthday?: string;
+}
+```
+
+
+No OpenAPI schema metadata. No `type?: string`.
+
+---
+
+## 🧠 Design Philosophy
+
+### Prisma as the Source of Truth
+
+Prisma already defines:
+
+- field types
+- nullability
+- relations
+- lists
+- enums
+
+This tool leverages that information to generate correct OpenAPI schemas, instead of redefining them manually.
+
+---
+
+### Swagger-Autogen Friendly
+
+The generated `swagger.config.js` is intentionally designed to:
+
+- be plain JavaScript
+- be executable by Node.js
+- be consumed directly by swagger-autogen
+
+No runtime magic, no custom Swagger parser.
+
+---
+
+## ⚙️ Default Configuration
+
+```typescript
+{
+    controllersGlob: "./src/web/api/controllers/**/*.ts",
+    openapiOut: "./src/web/api/openapi.json",
+    serviceTitle: "My Service",
+    serverUrl: "http://localhost:3000",
+    omitFieldsInWriteDtos: ["id", "createdAt", "updatedAt"]
+}
+```
+
+---
+
+## 🧩 Requirements
+
+- Node.js ≥ 18
+- Prisma Client (@prisma/client)
+- swagger-autogen
+
+Prisma schema already generated (prisma generate)
+
+---
+
+## ⚠️ Common Pitfalls
+1. Missing request bodies in Swagger UI
+
+Controllers still need proper swagger-autogen annotations:
+
+```typescript
+/* #swagger.requestBody = {
+    required: true,
+        content: {
+            "application/json": {
+                schema: { $ref: "#/components/schemas/PostUserRequest" }
+            }
+        }
+    } */
+```
+
+
+This tool provides the schemas — the controller annotations wire them up.
+
+2. Primitive types leaking as OpenAPI schema objects
+
+If your generated TypeScript client contains types like this:
+
+```typescript
+name?: {
+    type?: string;
+    format?: string;
+};
+```
+
+
+then your OpenAPI schemas are being interpreted as schema definitions instead of data shapes.
+
+This usually happens when:
+
+- OpenAPI schemas expose type, properties, items, etc. as part of the object
+- TypeScript generators mirror those schema internals instead of resolving them
+
+✔ This tool explicitly generates schemas in a way that swagger-autogen + swagger-typescript-api interpret as real DTOs, resulting in:
+
+`name?: string;`
+
+If you still see `type?: string` fields in your client:
+
+- ensure the OpenAPI spec was generated using the swagger.config.js from this tool
+- ensure you regenerated the client after regenerating openapi.json
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome, especially for:
+
+- Prisma edge cases
+- Advanced relation handling
+- Custom schema naming strategies
+
+---
+
+## ⭐ Summary
+
+Prisma Swagger Autogen enables you to:
+
+- define your API models once (in Prisma)
+- automatically expose them in Swagger
+- generate clean, usable API clients
+- keep documentation, backend, and frontend in sync

package/dist/chunk-SNNQZQLO.js

@@ -0,0 +1,334 @@
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import { globSync } from "glob";
+import { execSync } from "child_process";
+var CONFIG = {
+  projectRoot: process.cwd(),
+  controllersGlob: "./src/web/api/controllers/**/*.ts",
+  outFile: "./swagger.config.js",
+  openapiOut: "./src/web/api/openapi.json",
+  serviceTitle: "Prescription Service",
+  serverUrl: "http://localhost:3008",
+  securitySchemeName: "keycloakOAuth",
+  oauth: {
+    tokenUrl: "http://auth.localhost/realms/haemo/protocol/openid-connect/token",
+    refreshUrl: "http://auth.localhost/realms/haemo/protocol/openid-connect/refresh",
+    scopes: { openid: "openid scope" }
+  },
+  omitFieldsInWriteDtos: /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt", "v"])
+};
+function ensurePosix(p) {
+  return p.split(path.sep).join(path.posix.sep);
+}
+function pluralize(name) {
+  if (name.endsWith("s")) return `${name}es`;
+  return `${name}s`;
+}
+function scalarToSchema(scalar) {
+  switch (scalar) {
+    case "String":
+      return { type: "string" };
+    case "Boolean":
+      return { type: "boolean" };
+    case "Int":
+      return { type: "integer" };
+    case "BigInt":
+      return { type: "integer", format: "int64" };
+    case "Float":
+      return { type: "number" };
+    case "Decimal":
+      return { type: "number" };
+    case "DateTime":
+      return { type: "string", format: "date-time" };
+    case "Json":
+      return { type: "object" };
+    case "Bytes":
+      return { type: "string", format: "byte" };
+    default:
+      return { type: "string" };
+  }
+}
+function fieldSchema(field, getRefName) {
+  if (field.kind === "scalar") {
+    const base = scalarToSchema(field.type);
+    if (field.isList) return { type: "array", items: base };
+    return base;
+  }
+  if (field.kind === "enum") {
+    const base = { $ref: `#/components/schemas/${field.type}` };
+    if (field.isList) return { type: "array", items: base };
+    return base;
+  }
+  if (field.kind === "object") {
+    const ref = { $ref: `#/components/schemas/${getRefName(String(field.type))}` };
+    if (field.isList) return { type: "array", items: ref };
+    return ref;
+  }
+  return { type: "object" };
+}
+function modelToGetSchema(model, getRefName) {
+  const properties = {};
+  const required = [];
+  for (const f of model.fields) {
+    properties[f.name] = fieldSchema(f, getRefName);
+    if (f.isRequired) required.push(f.name);
+  }
+  const schema = { type: "object", properties };
+  if (required.length) schema.required = required;
+  return schema;
+}
+function stripWriteFields(model, getSchema, omit) {
+  const schema = JSON.parse(JSON.stringify(getSchema));
+  if (!schema.properties) return schema;
+  const relationFieldNames = new Set(model.fields.filter((f) => f.kind === "object").map((f) => f.name));
+  for (const key of Object.keys(schema.properties)) {
+    if (omit.has(key) || relationFieldNames.has(key)) delete schema.properties[key];
+  }
+  if (Array.isArray(schema.required)) {
+    schema.required = schema.required.filter((k) => !omit.has(k) && !relationFieldNames.has(k));
+    if (schema.required.length === 0) delete schema.required;
+  }
+  return schema;
+}
+function makeAllOptional(schema) {
+  const s = JSON.parse(JSON.stringify(schema));
+  delete s.required;
+  return s;
+}
+function listResponseSchema(itemRef) {
+  return {
+    type: "object",
+    properties: {
+      count: { type: "number", example: 3 },
+      hasPreviousPage: { type: "boolean", example: false },
+      hasNextPage: { type: "boolean", example: true },
+      pageNumber: { type: "number", example: 1 },
+      pageSize: { type: "number", example: 10 },
+      totalPages: { type: "number", example: 1 },
+      items: { type: "array", items: { $ref: itemRef } }
+    },
+    required: ["count", "hasPreviousPage", "hasNextPage", "pageNumber", "pageSize", "totalPages", "items"]
+  };
+}
+function exampleForScalarType(type, format) {
+  if (type === "string" && format === "date-time") return (/* @__PURE__ */ new Date(0)).toISOString();
+  switch (type) {
+    case "string":
+      return "string";
+    case "integer":
+      return 0;
+    case "number":
+      return 0;
+    case "boolean":
+      return true;
+    case "object":
+      return {};
+    default:
+      return null;
+  }
+}
+function buildExampleFromSchema(schema, components, depth = 0) {
+  if (depth > 2) return void 0;
+  if (schema.$ref) {
+    const name = String(schema.$ref).split("/").pop() || "";
+    const target = components[name];
+    if (!target) return void 0;
+    return buildExampleFromSchema(target, components, depth + 1);
+  }
+  if (Array.isArray(schema.allOf) && schema.allOf.length) {
+    const merged = {};
+    for (const part of schema.allOf) {
+      const ex = buildExampleFromSchema(part, components, depth + 1);
+      if (ex && typeof ex === "object" && !Array.isArray(ex)) Object.assign(merged, ex);
+    }
+    return Object.keys(merged).length ? merged : void 0;
+  }
+  if (schema.type === "array" && schema.items) {
+    const item = buildExampleFromSchema(schema.items, components, depth + 1);
+    return item === void 0 ? [] : [item];
+  }
+  if (schema.type === "object" && schema.properties) {
+    const obj = {};
+    for (const [k, v] of Object.entries(schema.properties)) {
+      const ex = buildExampleFromSchema(v, components, depth + 1);
+      if (ex !== void 0) obj[k] = ex;
+    }
+    return obj;
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length) return schema.enum[0];
+  if (typeof schema.type === "string") return exampleForScalarType(schema.type, schema.format);
+  return void 0;
+}
+function attachExample(schema, components) {
+  const s = JSON.parse(JSON.stringify(schema));
+  if (s.example === void 0) {
+    const ex = buildExampleFromSchema(s, components);
+    if (ex !== void 0) s.example = ex;
+  }
+  return s;
+}
+async function loadDmmfFromProject() {
+  const schemaPath = path.resolve(process.cwd(), "prisma/schema.prisma");
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Prisma schema not found at: ${schemaPath}`);
+  }
+  const cmd = `npx prisma generate --schema "${schemaPath}" --print`;
+  const stdout = execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  const firstBrace = stdout.indexOf("{");
+  const lastBrace = stdout.lastIndexOf("}");
+  if (firstBrace === -1 || lastBrace === -1) {
+    throw new Error(`Failed to parse Prisma DMMF from: ${cmd}`);
+  }
+  const jsonText = stdout.slice(firstBrace, lastBrace + 1);
+  const parsed = JSON.parse(jsonText);
+  const dmmf = parsed?.dmmf ?? parsed;
+  if (!dmmf?.datamodel?.models) {
+    throw new Error(`Prisma DMMF not found in prisma output. Got keys: ${Object.keys(parsed || {})}`);
+  }
+  return dmmf;
+}
+function buildSchemasFromDmmf(dmmf) {
+  const schemas = {};
+  const getRefName = (modelName) => `Get${modelName}Response`;
+  for (const e of dmmf.datamodel.enums) {
+    schemas[e.name] = { type: "string", enum: e.values.map((v) => v.name) };
+  }
+  for (const model of dmmf.datamodel.models) {
+    const getName = `Get${model.name}Response`;
+    const postName = `Post${model.name}Request`;
+    const putName = `Put${model.name}Request`;
+    const listName = `List${pluralize(model.name)}Response`;
+    const getSchema = modelToGetSchema(model, getRefName);
+    const postSchema = stripWriteFields(model, getSchema, CONFIG.omitFieldsInWriteDtos);
+    const putSchema = makeAllOptional(postSchema);
+    schemas[getName] = getSchema;
+    schemas[postName] = postSchema;
+    schemas[putName] = putSchema;
+    schemas[listName] = listResponseSchema(`#/components/schemas/${getName}`);
+  }
+  schemas["ExceptionResponse"] = {
+    type: "object",
+    properties: {
+      detail: { type: "string" },
+      errors: { type: "array", items: { type: "string" } },
+      status: { type: "number" },
+      title: { type: "string" },
+      type: { type: "string" }
+    },
+    required: ["status", "title", "type"]
+  };
+  schemas["BadRequestResponse"] = {
+    allOf: [{ $ref: "#/components/schemas/ExceptionResponse" }],
+    example: {
+      status: 400,
+      title: "The request was invalid",
+      type: "https://tools.ietf.org/html/rfc7231#section-6.5.1"
+    }
+  };
+  schemas["NotFoundResponse"] = {
+    allOf: [{ $ref: "#/components/schemas/ExceptionResponse" }],
+    example: {
+      status: 404,
+      title: "The specified resource was not found",
+      type: "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4"
+    }
+  };
+  schemas["InternalErrorResponse"] = {
+    allOf: [{ $ref: "#/components/schemas/ExceptionResponse" }],
+    example: {
+      status: 500,
+      title: "An error occurred while processing your request",
+      type: "https://tools.ietf.org/html/rfc7231#section-6.6.1"
+    }
+  };
+  for (const name of Object.keys(schemas)) {
+    if (name.startsWith("Post") && name.endsWith("Request")) schemas[name] = attachExample(schemas[name], schemas);
+    if (name.startsWith("Put") && name.endsWith("Request")) schemas[name] = attachExample(schemas[name], schemas);
+  }
+  return schemas;
+}
+function generateSwaggerConfigJs(schemas) {
+  const routes = globSync(CONFIG.controllersGlob, { nodir: true }).map((p) => ensurePosix(p));
+  const docs = {
+    info: { title: CONFIG.serviceTitle },
+    servers: [{ url: CONFIG.serverUrl }],
+    components: {
+      schemas,
+      securitySchemes: {
+        [CONFIG.securitySchemeName]: {
+          type: "oauth2",
+          description: "This API uses OAuth2 with the password flow.",
+          flows: {
+            password: {
+              tokenUrl: CONFIG.oauth.tokenUrl,
+              refreshUrl: CONFIG.oauth.refreshUrl,
+              scopes: CONFIG.oauth.scopes
+            }
+          }
+        }
+      }
+    },
+    security: [{ [CONFIG.securitySchemeName]: ["openid"] }]
+  };
+  const fileContent = `const swaggerAutogen = require('swagger-autogen')();
+const fs = require('fs');
+const path = require('node:path');
+
+function isPlainObject(v){return v!==null && typeof v==='object' && !Array.isArray(v);}
+
+function normalizeSchema(schema){
+	if(!isPlainObject(schema)) return schema;
+	if(schema.$ref) return schema;
+
+	if(isPlainObject(schema.type) && typeof schema.type.example === 'string') schema.type = schema.type.example;
+	if(isPlainObject(schema.format) && typeof schema.format.example === 'string') schema.format = schema.format.example;
+	if(isPlainObject(schema.required) && Array.isArray(schema.required.example)) schema.required = schema.required.example;
+	if(isPlainObject(schema.enum) && Array.isArray(schema.enum.example)) schema.enum = schema.enum.example;
+
+	if(Array.isArray(schema.allOf)) schema.allOf = schema.allOf.map(normalizeSchema);
+	if(isPlainObject(schema.items)) schema.items = normalizeSchema(schema.items);
+	if(isPlainObject(schema.additionalProperties)) schema.additionalProperties = normalizeSchema(schema.additionalProperties);
+
+	if(isPlainObject(schema.properties)){
+		for(const k of Object.keys(schema.properties)){
+			schema.properties[k] = normalizeSchema(schema.properties[k]);
+		}
+	}
+
+	return schema;
+}
+
+function fixOpenApiFile(openapiPath){
+	const abs = path.resolve(process.cwd(), openapiPath);
+	if(!fs.existsSync(abs)) return;
+	const doc = JSON.parse(fs.readFileSync(abs,'utf8'));
+
+	if(doc && doc.components && isPlainObject(doc.components.schemas)){
+		for(const name of Object.keys(doc.components.schemas)){
+			doc.components.schemas[name] = normalizeSchema(doc.components.schemas[name]);
+		}
+	}
+
+	fs.writeFileSync(abs, JSON.stringify(doc,null,2),'utf8');
+}
+
+const docs = ${JSON.stringify(docs, null, 2)};
+const routes = ${JSON.stringify(routes, null, 2)};
+
+swaggerAutogen('${ensurePosix(CONFIG.openapiOut)}', routes, docs)
+	.then(() => fixOpenApiFile('${ensurePosix(CONFIG.openapiOut)}'))
+	.catch((e) => { console.error(e); process.exitCode = 1; });
+`;
+  const outPath = path.resolve(CONFIG.projectRoot, CONFIG.outFile);
+  fs.writeFileSync(outPath, fileContent, "utf8");
+}
+async function run(_args) {
+  const dmmf = await loadDmmfFromProject();
+  const schemas = buildSchemasFromDmmf(dmmf);
+  generateSwaggerConfigJs(schemas);
+}
+
+export {
+  run
+};