create-daloy 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
   "type": "module",
   "license": "MIT",

package/templates/node-basic/README.md

@@ -16,6 +16,13 @@ curl http://localhost:3000/healthz
 curl http://localhost:3000/books/1
 ```
 
+## API documentation
+
+- Scalar UI:  <http://localhost:3000/docs>
+- OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
+
+The spec is generated live from your routes, so it stays in sync with what is actually deployed.
+
 ## Generate OpenAPI + typed client
 
 ```bash

package/templates/node-basic/src/index.ts

@@ -7,6 +7,8 @@ import {
   secureHeaders,
 } from "@daloyjs/core";
 import { serve } from "@daloyjs/core/node";
+import { generateOpenAPI } from "@daloyjs/core/openapi";
+import { htmlResponse, scalarHtml } from "@daloyjs/core/docs";
 
 const app = new App({
   bodyLimitBytes: 1024 * 1024,
@@ -59,5 +61,45 @@ app.route({
 });
 
 const port = Number(process.env.PORT ?? 3000);
+
+// --- API documentation -----------------------------------------------------
+// `/openapi.json` returns the live OpenAPI 3.1 spec generated from the routes
+// defined above. `/docs` serves a Scalar UI page that loads that spec.
+
+app.route({
+  method: "GET",
+  path: "/openapi.json",
+  operationId: "getOpenAPI",
+  tags: ["Docs"],
+  responses: { 200: { description: "OpenAPI 3.1 document" } },
+  handler: async () => ({
+    status: 200 as const,
+    body: generateOpenAPI(app, {
+      info: { title: "My Daloy API", version: "0.0.1" },
+      servers: [{ url: `http://localhost:${port}` }],
+    }),
+  }),
+});
+
+app.route({
+  method: "GET",
+  path: "/docs",
+  operationId: "docs",
+  tags: ["Docs"],
+  responses: { 200: { description: "API reference UI" } },
+  handler: async () => {
+    const html = scalarHtml({ specUrl: "/openapi.json", title: "My Daloy API" });
+    const res = htmlResponse(html);
+    return {
+      status: 200 as const,
+      body: html,
+      headers: Object.fromEntries(res.headers),
+    };
+  },
+});
+
 serve(app, { port });
 console.log(`DaloyJS listening on http://localhost:${port}`);
+console.log(`  API docs:    http://localhost:${port}/docs`);
+console.log(`  OpenAPI JSON: http://localhost:${port}/openapi.json`);
+console.log(`  Health:       http://localhost:${port}/healthz`);

package/templates/vercel-edge/README.md

@@ -16,6 +16,13 @@ curl http://localhost:3000/healthz
 curl http://localhost:3000/books/1
 ```
 
+## API documentation
+
+- Scalar UI:  <http://localhost:3000/docs>
+- OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
+
+After deploying, the same routes serve `/docs` and `/openapi.json` from your Vercel Edge URL.
+
 ## Deploy
 
 ```bash

package/templates/vercel-edge/api/[...path].ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { App, NotFoundError, requestId, secureHeaders } from "@daloyjs/core";
 import { toEdgeHandler } from "@daloyjs/core/vercel";
+import { generateOpenAPI } from "@daloyjs/core/openapi";
+import { htmlResponse, scalarHtml } from "@daloyjs/core/docs";
 
 export const config = { runtime: "edge" };
 
@@ -26,7 +28,7 @@ app.route({
   },
   handler: async () => ({
     status: 200,
-    body: { ok: true, runtime: "vercel-edge" as const },
+    body: { ok: true as const, runtime: "vercel-edge" as const },
   }),
 });
 
@@ -52,4 +54,39 @@ app.route({
   },
 });
 
+// --- API documentation -----------------------------------------------------
+// `/openapi.json` returns the OpenAPI 3.1 spec generated from the routes above.
+// `/docs` serves a Scalar UI page that loads that spec.
+
+app.route({
+  method: "GET",
+  path: "/openapi.json",
+  operationId: "getOpenAPI",
+  tags: ["Docs"],
+  responses: { 200: { description: "OpenAPI 3.1 document" } },
+  handler: async () => ({
+    status: 200 as const,
+    body: generateOpenAPI(app, {
+      info: { title: "My Daloy Edge API", version: "0.0.1" },
+    }),
+  }),
+});
+
+app.route({
+  method: "GET",
+  path: "/docs",
+  operationId: "docs",
+  tags: ["Docs"],
+  responses: { 200: { description: "API reference UI" } },
+  handler: async () => {
+    const html = scalarHtml({ specUrl: "/openapi.json", title: "My Daloy Edge API" });
+    const res = htmlResponse(html);
+    return {
+      status: 200 as const,
+      body: html,
+      headers: Object.fromEntries(res.headers),
+    };
+  },
+});
+
 export default toEdgeHandler(app);