argsbarg 6.1.3 → 6.1.4

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.4] - 2026-07-24
+
+### Changed
+
+- **`GET /swagger`** — Swagger UI API reference (replaces `GET /openapi-browser` and Scalar).
+- **`GET /openapi.json`** — documents `/health`, `/health/live`, and `/health/ready` probe endpoints under a **Health** tag.
+- **OpenAPI tags** — user `/api/*` routes are grouped by top-level command key (router `description` becomes the tag description).
+
 ## [6.1.3] - 2026-07-24
 
 ### Added
@@ -833,7 +841,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.4...HEAD
+[6.1.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.4
 [6.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.3
 [6.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.2
 [6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1

package/docs/http-server.md

@@ -73,8 +73,8 @@ Per-surface exposure: `http.enabled: false` removes a leaf from the route table;
 | --- | --- | --- |
 | `GET` | `/health` or `/health/live` | Liveness — 200 when server is listening |
 | `GET` | `/health/ready` | Readiness — config + optional `program.readiness` |
-| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
-| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
+| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths (includes `/health/*` and `/api/*`) |
+| `GET` | `/swagger` | Interactive Swagger UI API reference (CDN) |
 | `*` | `/api/...` | Invoke user commands (method per route) |
 | `OPTIONS` | `*` | CORS preflight (`GET, POST, PUT, PATCH, DELETE`) |
 
@@ -86,7 +86,7 @@ Per-surface exposure: `http.enabled: false` removes a leaf from the route table;
 curl -s http://127.0.0.1:3000/health
 curl -s http://127.0.0.1:3000/health/ready
 curl -s http://127.0.0.1:3000/openapi.json
-open http://127.0.0.1:3000/openapi-browser
+open http://127.0.0.1:3000/swagger
 curl -s http://127.0.0.1:3000/api/workspaces
 curl -s -X POST http://127.0.0.1:3000/api/workspaces \
   -H 'content-type: application/json' \

package/examples/full-example/docs/cli-schema.json

@@ -191,7 +191,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -424,7 +424,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -679,7 +679,7 @@
         {
           "key": "http",
           "description": "HTTP API server for tools.",
-          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+          "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
           "options": [
             {
               "name": "host",
@@ -916,7 +916,7 @@
             {
               "key": "http",
               "description": "HTTP API server for tools.",
-              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
               "options": [
                 {
                   "name": "host",
@@ -1149,7 +1149,7 @@
             {
               "key": "http",
               "description": "HTTP API server for tools.",
-              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+              "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
               "options": [
                 {
                   "name": "host",
@@ -1386,7 +1386,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -1619,7 +1619,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -1852,7 +1852,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",
@@ -2085,7 +2085,7 @@
                 {
                   "key": "http",
                   "description": "HTTP API server for tools.",
-                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
+                  "notes": "HTTP tool server on http://127.0.0.1:3000.\n\nEndpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*\n\nConfigure app settings:\n\n  full-example configure\n\nFull setup guide: full-example docs http",
                   "options": [
                     {
                       "name": "host",

package/examples/full-example/docs/cli.md

@@ -213,7 +213,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -426,7 +426,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -667,7 +667,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -890,7 +890,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -1103,7 +1103,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -1327,7 +1327,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -1540,7 +1540,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -1753,7 +1753,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 
@@ -1966,7 +1966,7 @@ HTTP API server for tools.
 
 > HTTP tool server on http://127.0.0.1:3000.
 > 
-> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*
+> Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*
 > 
 > Configure app settings:
 > 

package/examples/full-example/docs/http.md

@@ -19,7 +19,7 @@ Bind is localhost-only in v0 — use a reverse proxy for remote access.
 | `GET` | `/health` or `/health/live` | Liveness check |
 | `GET` | `/health/ready` | Readiness (config + `program.readiness`) |
 | `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
-| `GET` | `/openapi-browser` | Interactive Scalar API reference |
+| `GET` | `/swagger` | Interactive Swagger UI API reference |
 | `*` | `/api/...` | Invoke user commands (method per route) |
 | `OPTIONS` | `*` | CORS preflight |
 
@@ -61,7 +61,7 @@ Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.
 
 POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).
 
-For HTTP clients, use **`GET /openapi.json`** (or **`GET /openapi-browser`**) for per-route request shapes.
+For HTTP clients, use **`GET /openapi.json`** (or **`GET /swagger`**) for per-route request shapes.
 
 Varargs positionals accept a JSON array of strings (not a comma-separated string).
 Options with `format: comma-list` accept a comma-separated string or JSON array.
@@ -73,7 +73,7 @@ Shell invocation reference: `full-example docs cli`. Full CLI tree JSON: `full-e
 
 The HTTP API is described in OpenAPI 3.1.
 
-- **Browse** — [http://127.0.0.1:3000/openapi-browser](http://127.0.0.1:3000/openapi-browser) (Scalar UI; loads `/openapi.json`)
+- **Browse** — [http://127.0.0.1:3000/swagger](http://127.0.0.1:3000/swagger) (Swagger UI; loads `/openapi.json`)
 - **Fetch** — `curl -s http://127.0.0.1:3000/openapi.json`
 - **Save offline** — `full-example docs openapi --save` → `./docs/openapi.json` (or `just docgen` in app repos)
 

package/examples/full-example/docs/openapi.json

@@ -202,6 +202,27 @@
               }
             }
           }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "description": "Message to echo back."
+                  }
+                },
+                "required": [
+                  "message"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.3",
+  "version": "6.1.4",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/builtins/http.ts

@@ -37,7 +37,7 @@ export function cliBuiltinHttpCommand(program: CliProgram): CliRouter {
   const lines = [
     `HTTP tool server on http://${hostname}:${port}.`,
     "",
-    "Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /openapi-browser, /api/*",
+    "Endpoints: GET /health, GET /health/ready, GET /openapi.json, GET /swagger, /api/*",
     "",
   ];
   if (caps.configure) {

package/src/docs/http-guide.ts

@@ -50,7 +50,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "| `GET` | `/health` or `/health/live` | Liveness check |",
     "| `GET` | `/health/ready` | Readiness (config + `program.readiness`) |",
     "| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |",
-    "| `GET` | `/openapi-browser` | Interactive Scalar API reference |",
+    "| `GET` | `/swagger` | Interactive Swagger UI API reference |",
     "| `*` | `/api/...` | Invoke user commands (method per route) |",
     "| `OPTIONS` | `*` | CORS preflight |",
     "",
@@ -111,7 +111,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
     "",
-    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-route request shapes.`,
+    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /swagger\`**) for per-route request shapes.`,
     "",
     "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
     "Options with `format: comma-list` accept a comma-separated string or JSON array.",
@@ -123,7 +123,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "The HTTP API is described in OpenAPI 3.1.",
     "",
-    `- **Browse** — [${baseUrl}/openapi-browser](${baseUrl}/openapi-browser) (Scalar UI; loads \`/openapi.json\`)`,
+    `- **Browse** — [${baseUrl}/swagger](${baseUrl}/swagger) (Swagger UI; loads \`/openapi.json\`)`,
     `- **Fetch** — \`curl -s ${baseUrl}/openapi.json\``,
     `- **Save offline** — \`${root.key} docs openapi --save\` → \`./docs/openapi.json\` (or \`just docgen\` in app repos)`,
     "",

package/src/http/openapi.ts

@@ -3,8 +3,8 @@ Hand-built OpenAPI 3.1 document from exposed HTTP REST routes.
 */
 
 import { collectOptionDefs } from "~/core/parse.ts";
-import type { CliHttpMethod, CliProgram } from "~/core/types.ts";
-import { CliOptionKind, isJsonLeaf } from "~/core/types.ts";
+import type { CliHttpMethod, CliNode, CliProgram } from "~/core/types.ts";
+import { CliOptionKind, isCliLeaf, isJsonLeaf } from "~/core/types.ts";
 import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
 import { dereferenceJsonSchema } from "./schema-deref.ts";
 
@@ -106,15 +106,120 @@ function methodLower(method: CliHttpMethod): string {
   return method.toLowerCase();
 }
 
+const HEALTH_TAG = "health";
+
+const livenessResponseSchema = {
+  type: "object",
+  properties: { ok: { type: "boolean", const: true } },
+  required: ["ok"],
+} as const;
+
+const readinessCheckSchema = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean" },
+    error: { type: "string" },
+    missing: { type: "array", items: { type: "string" } },
+  },
+  required: ["ok"],
+} as const;
+
+const readinessResponseSchema = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean" },
+    checks: {
+      type: "object",
+      properties: {
+        config_file: readinessCheckSchema,
+        config_required: readinessCheckSchema,
+        custom: readinessCheckSchema,
+      },
+      required: ["config_file", "config_required", "custom"],
+    },
+  },
+  required: ["ok", "checks"],
+} as const;
+
+function jsonResponseEntry(description: string, schema: Record<string, unknown>): Record<string, unknown> {
+  return {
+    description,
+    content: {
+      [JSON_CONTENT_TYPE]: { schema },
+    },
+  };
+}
+
+function livenessGetOp(operationId: string, summary: string): Record<string, unknown> {
+  return {
+    tags: [HEALTH_TAG],
+    operationId,
+    summary,
+    responses: {
+      "200": jsonResponseEntry("Server is listening", livenessResponseSchema),
+    },
+  };
+}
+
+/** Framework health probe paths served alongside `/api/*` routes. */
+function buildHealthPaths(): Record<string, unknown> {
+  return {
+    "/health": {
+      get: livenessGetOp("health", "Liveness probe (alias of /health/live)"),
+    },
+    "/health/live": {
+      get: livenessGetOp("health_live", "Liveness probe"),
+    },
+    "/health/ready": {
+      get: {
+        tags: [HEALTH_TAG],
+        operationId: "health_ready",
+        summary: "Readiness probe",
+        description: "Config file, required app config, and optional program.readiness checks.",
+        responses: {
+          "200": jsonResponseEntry("Ready to serve traffic", readinessResponseSchema),
+          "503": jsonResponseEntry("Not ready", readinessResponseSchema),
+        },
+      },
+    },
+  };
+}
+
+type HttpRoute = ReturnType<typeof collectHttpRoutes>[number];
+
+/** Top-level command key for OpenAPI grouping (first non-`:param` segment). */
+function topLevelCommandKey(route: HttpRoute, program: CliProgram): string {
+  const key = route.commandPath.find((k) => !k.startsWith(":"));
+  return key ?? program.key;
+}
+
+function findTopLevelCommand(program: CliProgram, key: string): CliNode | undefined {
+  if (isCliLeaf(program)) {
+    return program.key === key ? program : undefined;
+  }
+  return program.commands.find((c) => c.key === key);
+}
+
+/** OpenAPI tags for user `/api/*` routes, one per top-level command. */
+function collectCommandTags(program: CliProgram, routes: HttpRoute[]): { name: string; description?: string }[] {
+  const names = [...new Set(routes.map((route) => topLevelCommandKey(route, program)))].sort();
+  return names.map((name) => {
+    const node = findTopLevelCommand(program, name);
+    return node?.description ? { name, description: node.description } : { name };
+  });
+}
+
 /** Generates an OpenAPI 3.1 document for the program's HTTP routes. */
 export function generateOpenApi(program: CliProgram): Record<string, unknown> {
   const routes = collectHttpRoutes(program);
-  const paths: Record<string, unknown> = {};
+  const paths: Record<string, unknown> = program.httpServer?.enabled ? buildHealthPaths() : {};
+  const commandTags = collectCommandTags(program, routes);
 
   for (const route of routes) {
     const pathKey = route.openApiPath;
     const existing = (paths[pathKey] as Record<string, unknown> | undefined) ?? {};
     const op: Record<string, unknown> = {
+      tags: [topLevelCommandKey(route, program)],
       operationId: route.openApiPath.replace(/\//g, "_").replace(/[{}]/g, ""),
       summary: route.leaf.description ?? route.leaf.key,
       responses: {
@@ -150,9 +255,9 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
           description: opt.description,
         })),
       ];
-    } else if (!isJsonLeaf(route.leaf)) {
+    } else {
       op.requestBody = {
-        required: false,
+        required: isJsonLeaf(route.leaf),
         content: {
           [JSON_CONTENT_TYPE]: {
             schema: dereferenceJsonSchema(buildInputSchema(program, route)),
@@ -172,6 +277,9 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
       version: program.version,
       description: program.description,
     },
+    ...(program.httpServer?.enabled
+      ? { tags: [{ name: HEALTH_TAG, description: "Server health probes" }, ...commandTags] }
+      : {}),
     paths,
   };
 }

package/src/http/result.ts

@@ -98,7 +98,7 @@ export function apiErrorResponse(status: number, body: ApiToolCallErrorBody): Re
   });
 }
 
-/** Scalar API reference HTML served at GET /openapi-browser. */
+/** Swagger UI HTML served at GET /swagger. */
 export function apiDocsHtml(): string {
   return `<!doctype html>
 <html lang="en">
@@ -106,15 +106,15 @@ export function apiDocsHtml(): string {
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>API Reference</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" />
 </head>
 <body>
-  <div id="api-reference"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin></script>
   <script>
-    Scalar.createApiReference("#api-reference", {
+    SwaggerUIBundle({
       url: "/openapi.json",
-      orderSchemaPropertiesBy: "preserve",
-      orderRequiredPropertiesFirst: false,
+      dom_id: "#swagger-ui",
     });
   </script>
 </body>

package/src/http/server.ts

@@ -129,7 +129,7 @@ export async function handleApiRequest(
     return finish(jsonResponse(200, generateOpenApi(root)));
   }
 
-  if (request.method === "GET" && path === "/openapi-browser") {
+  if (request.method === "GET" && path === "/swagger") {
     return finish(
       new Response(apiDocsHtml(), {
         status: 200,

package/src/test/integration/http.test.ts

@@ -432,19 +432,80 @@ describe("HTTP API routes", () => {
     const doc = (await res.json()) as { openapi: string; paths: Record<string, unknown> };
     expect(doc.openapi).toBe("3.1.0");
     expect(doc.paths["/api/stat/owner/lookup"]).toBeDefined();
+    expect(doc.paths["/health"]).toBeDefined();
+    expect(doc.paths["/health/live"]).toBeDefined();
+    expect(doc.paths["/health/ready"]).toBeDefined();
   });
 
-  test("GET /openapi-browser returns Scalar HTML", async () => {
-    const res = await apiRequest(program, new Request("http://127.0.0.1/openapi-browser"));
+  test("GET /swagger returns Swagger UI HTML", async () => {
+    const res = await apiRequest(program, new Request("http://127.0.0.1/swagger"));
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toContain("text/html");
     const html = await res.text();
-    expect(html).toContain("@scalar/api-reference");
-    expect(html).toContain('orderSchemaPropertiesBy: "preserve"');
-    expect(html).toContain("orderRequiredPropertiesFirst: false");
+    expect(html).toContain("swagger-ui-dist");
+    expect(html).toContain('url: "/openapi.json"');
+    expect(html).toContain('dom_id: "#swagger-ui"');
   });
 });
 
+test("generateOpenApi includes health probe paths", () => {
+  const program = testProgram({
+    key: "app",
+    description: "Test app",
+    httpServer: { enabled: true },
+    handler: () => ({ ok: true }),
+  });
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as {
+    tags: { name: string }[];
+    paths: Record<
+      string,
+      {
+        get: {
+          tags: string[];
+          responses: Record<string, { content: Record<string, { schema: Record<string, unknown> }> }>;
+        };
+      }
+    >;
+  };
+  expect(doc.tags.some((t) => t.name === "health")).toBe(true);
+  expect(doc.paths["/health"]?.get.tags).toContain("health");
+  expect(doc.paths["/health/live"]?.get.responses["200"]).toBeDefined();
+  expect(doc.paths["/health/ready"]?.get.responses["200"]).toBeDefined();
+  expect(doc.paths["/health/ready"]?.get.responses["503"]).toBeDefined();
+  const readySchema = doc.paths["/health/ready"]?.get.responses["200"].content["application/json; charset=utf-8"]
+    .schema as { properties?: { checks?: unknown } };
+  expect(readySchema.properties?.checks).toBeDefined();
+});
+
+test("generateOpenApi omits health paths when httpServer disabled", () => {
+  const program = testProgram({
+    key: "app",
+    description: "Test app",
+    handler: () => ({ ok: true }),
+  });
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as { paths: Record<string, unknown> };
+  expect(doc.paths["/health"]).toBeUndefined();
+});
+
+test("generateOpenApi groups routes by top-level command tag", () => {
+  const program = nestedApiFixture();
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as {
+    tags: { name: string; description?: string }[];
+    paths: Record<string, { post?: { tags: string[] }; get?: { tags: string[] } }>;
+  };
+  const tagNames = doc.tags.map((t) => t.name);
+  expect(tagNames).toContain("health");
+  expect(tagNames).toContain("stat");
+  expect(tagNames).toContain("pdf");
+  expect(doc.tags.find((t) => t.name === "stat")?.description).toBe("File metadata.");
+  expect(doc.paths["/api/stat/owner/lookup"]?.post?.tags).toEqual(["stat"]);
+  expect(doc.paths["/api/pdf"]?.post?.tags).toEqual(["pdf"]);
+  expect(doc.paths["/api/read"]?.post?.tags).toEqual(["read"]);
+});
+
 test("generateOpenApi maps binary content types", () => {
   const program = nestedApiFixture();
   const doc = generateOpenApi(program) as {
@@ -505,6 +566,52 @@ test("generateOpenApi dereferences nested inputSchema definitions", () => {
   });
 });
 
+test("generateOpenApi generates requestBody for kind: json leaves", () => {
+  const program = testProgram({
+    key: "app",
+    description: "Test app",
+    httpServer: { enabled: true },
+    commands: [
+      {
+        key: "render-invoice",
+        description: "Render an invoice.",
+        kind: "json",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+          },
+          required: ["id"],
+        },
+        handler: () => ({ ok: true }),
+      },
+    ],
+  });
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as {
+    paths: Record<
+      string,
+      {
+        post: {
+          requestBody: {
+            required: boolean;
+            content: Record<string, { schema: Record<string, unknown> }>;
+          };
+        };
+      }
+    >;
+  };
+  const op = doc.paths["/api/render-invoice"]?.post;
+  expect(op).toBeDefined();
+  expect(op.requestBody).toBeDefined();
+  expect(op.requestBody.required).toBe(true);
+  expect(op.requestBody.content["application/json; charset=utf-8"].schema).toEqual({
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  });
+});
+
 test("ctx.respond throws when called twice", () => {
   const program = testProgram({
     key: "app",