@nwire/openapi 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,39 @@
+# @nwire/openapi
+
+> OpenAPI 3.1 generation from a Nwire wire collection — transport-agnostic.
+
+```bash
+pnpm add @nwire/openapi
+```
+
+`generateOpenApi(wires)` reads `app.interface.wires`, picks the HTTP bindings,
+and emits an OpenAPI 3.1 document from each binding's `openapi` metadata and its
+zod schemas. No HTTP server and no framework lock-in: an HTTP adopter (koa,
+express) serves the result, and a build step can write it to a file without
+booting a transport.
+
+```ts
+import { generateOpenApi } from "@nwire/openapi";
+
+const spec = await generateOpenApi(app.interface.wires, {
+  title: "Orders API",
+  version: "1.0.0",
+  prefix: "/api",
+});
+// serve `JSON.stringify(spec)` at /openapi.json, or write it to disk
+```
+
+This package owns `@asteasolutions/zod-to-openapi` as a direct dependency, so the
+generator is always present where generation lives and a consumer produces a spec
+with nothing extra to install.
+
+## Options
+
+| Option                              | Meaning                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `title` / `version` / `description` | `info` block of the document                                            |
+| `serverUrl`                         | a single entry for the `servers` array                                  |
+| `prefix`                            | path prefix prepended to every route (match your HTTP adopter's prefix) |
+
+Bindings carry the rest: `operation`, `summary`, `tags`, request schemas
+(`params` / `query` / `body`), and `returns` / `errors` for responses.

package/dist/openapi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@nwire/openapi` — turn a Nwire wire collection into an OpenAPI 3.1 document.
+ *
+ * Transport-agnostic by design: it reads `app.interface.wires`, picks the HTTP
+ * bindings, and emits one path entry per `(verb, path)` from the binding's
+ * `openapi` metadata + zod schemas. No HTTP server, no koa — any HTTP adopter
+ * (koa, express) serves the result, and a CLI can write it to a file
+ * (`nwire openapi > spec.json`) without booting a transport.
+ *
+ * `@asteasolutions/zod-to-openapi` is a direct dependency, so the generator is
+ * always present wherever generation lives; a consumer serves `/openapi.json`
+ * without installing anything extra.
+ */
+import type { Wire } from "@nwire/wires";
+export interface GenerateOpenApiOptions {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly serverUrl?: string;
+    /** Prefix the spec paths with this. Match the HTTP adopter prefix. */
+    readonly prefix?: string;
+}
+/**
+ * Build an OpenAPI 3.1 document from a wire collection.
+ *
+ * Returns a promise — HTTP adapters `await` it at mount time.
+ */
+export declare function generateOpenApi(wires: ReadonlyArray<Wire>, options?: GenerateOpenApiOptions): Promise<object>;

package/dist/openapi.js

@@ -0,0 +1,96 @@
+/**
+ * `@nwire/openapi` — turn a Nwire wire collection into an OpenAPI 3.1 document.
+ *
+ * Transport-agnostic by design: it reads `app.interface.wires`, picks the HTTP
+ * bindings, and emits one path entry per `(verb, path)` from the binding's
+ * `openapi` metadata + zod schemas. No HTTP server, no koa — any HTTP adopter
+ * (koa, express) serves the result, and a CLI can write it to a file
+ * (`nwire openapi > spec.json`) without booting a transport.
+ *
+ * `@asteasolutions/zod-to-openapi` is a direct dependency, so the generator is
+ * always present wherever generation lives; a consumer serves `/openapi.json`
+ * without installing anything extra.
+ */
+import { OpenAPIRegistry, OpenApiGeneratorV31, extendZodWithOpenApi, } from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+// Patch zod's prototype with `.openapi()` once, at module load. It applies
+// retroactively to every schema instance the bindings already hold, so the
+// order of "build schema" vs "load this module" doesn't matter.
+extendZodWithOpenApi(z);
+function isOpenApiBinding(b) {
+    return (typeof b === "object" &&
+        b !== null &&
+        b.$adapter === "http" &&
+        typeof b.verb === "string" &&
+        typeof b.path === "string");
+}
+// Convert wire-style `/users/:id` to OpenAPI `{id}` notation.
+function toOpenApiPath(p) {
+    return p.replace(/:(\w+)/g, "{$1}");
+}
+/**
+ * Build an OpenAPI 3.1 document from a wire collection.
+ *
+ * Returns a promise — HTTP adapters `await` it at mount time.
+ */
+export async function generateOpenApi(wires, options = {}) {
+    const registry = new OpenAPIRegistry();
+    const prefix = options.prefix ?? "";
+    for (const wire of wires) {
+        if (!isOpenApiBinding(wire.binding))
+            continue;
+        const b = wire.binding;
+        if (!b.openapi)
+            continue;
+        const path = prefix + toOpenApiPath(b.path);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const responses = {
+            "200": { description: "Success" },
+        };
+        // Returns from the binding override the default 200 envelope.
+        if (b.openapi.returns?.length) {
+            const first = b.openapi.returns[0];
+            const status = String(first?.status ?? 200);
+            const schema = first?.resource?.schema;
+            responses[status] = schema
+                ? {
+                    description: "Success",
+                    content: { "application/json": { schema } },
+                }
+                : { description: "Success" };
+        }
+        if (b.openapi.errors?.length) {
+            for (const e of b.openapi.errors) {
+                if (typeof e.status === "number") {
+                    responses[String(e.status)] = {
+                        description: e.code ?? "Error",
+                    };
+                }
+            }
+        }
+        registry.registerPath({
+            method: b.verb,
+            path,
+            operationId: b.openapi.operation,
+            tags: b.openapi.tags ? [...b.openapi.tags] : undefined,
+            summary: b.openapi.summary,
+            description: b.openapi.description,
+            request: {
+                ...(b.params ? { params: b.params } : {}),
+                ...(b.query ? { query: b.query } : {}),
+                ...(b.body ? { body: { content: { "application/json": { schema: b.body } } } } : {}),
+            },
+            responses,
+        });
+    }
+    const generator = new OpenApiGeneratorV31(registry.definitions);
+    return generator.generateDocument({
+        openapi: "3.1.0",
+        info: {
+            title: options.title ?? "API",
+            version: options.version ?? "1.0.0",
+            description: options.description,
+        },
+        servers: options.serverUrl ? [{ url: options.serverUrl }] : undefined,
+    });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nwire/openapi",
+  "version": "0.14.0",
+  "description": "Nwire — OpenAPI 3.1 generation from a Nwire wire collection. Transport-agnostic: reads app.interface.wires, picks the HTTP bindings, and emits a spec from binding metadata + zod schemas. Owns @asteasolutions/zod-to-openapi as a direct dependency, so any HTTP adopter (koa, express) or a CLI produces a spec with nothing extra to install.",
+  "keywords": [
+    "nwire",
+    "openapi",
+    "spec",
+    "swagger"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/openapi.js",
+  "types": "./dist/openapi.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/openapi.js",
+      "types": "./dist/openapi.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "zod": "^4.0.0",
+    "@nwire/wires": "0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}