@tetsujs/openapi 0.5.2 → 0.6.0

package/README.md

@@ -91,12 +91,12 @@ wrote, by a rule:
 | parameters | `schema.params`, `query`, `headers`, `cookies` | required as the schema says |
 | the request body | `schema.body` and `bodyType` | media types from `bodyType`; required unless `text` or `stream` |
 | `security` | `secured()` hooks, of every level the route runs under | every hook required together; `anyOf` inside one hook is the alternatives |
-| the statuses | the route's `schema.response`, the hooks' `documented()` and `secured()`, the framework | one schema is `200`, a map its statuses, `null` a status without a body; with no `2xx` declared, `200`; the framework's `422`, `400`, `413`, `500` where they can happen — see [Responses the framework adds](#responses-the-framework-adds) |
+| the statuses | the route's `schema.response`, the hooks' `documented()` and `secured()`, the framework | one schema is `200`, a map its statuses, `null` or an entry without `body` a status without a body; with no `schema.response` at all, `200`; the framework's `422`, `400`, `413`, `500` where they can happen — see [Responses the framework adds](#responses-the-framework-adds) |
 | a status's body | everything answering with that status | one flat `anyOf`, the route's own first, the same body once |
 | an error envelope | any of them | one definition per status and code in `components`, named after the code; the route's own kept |
 | `discriminator` | the envelopes of a status | on `error`, or the format's field, when every alternative is an envelope |
 | a status's description | the schemas' `description`, the hooks', the framework's | one is the description, several a list led by code, none the reason phrase |
-| a status's headers | the hooks' `documented()` headers | possible, not required |
+| a status's headers | the route's entry — `{ body, headers, cookies }` — and the hooks' `documented()` headers | the route's required as its schema says, a property's `description` the header's; its cookies one `set-cookie` header listing them; a hook's possible, not required; the route's wins a name both give |
 | the document's `tags` | the `tags` option | in its order, then the tags routes use and it leaves out |
 
 `docs: { hidden: true }` leaves a route out of the document; it is served
@@ -124,9 +124,24 @@ the routes use and `tags` leaves out is listed after them, in the order
 the routes first use it, and reported — it is usually one tag spelled two
 ways, `sign_in` next to `sign-in`. So is a tag described and used by no
 operation. Without `tags` the document lists none, and nothing is
-reported. An application of several surfaces, each with its own `docs()`,
-gives each one only the tags of its own routes: given all of them, every
-`docs()` reports the tags of the others as unused.
+reported.
+
+A `docs()` documents the application it is mounted in, all of it. Several
+surfaces with a document each — a public API and an admin one — are
+several applications, each with its own `docs()` and only the tags of its
+own routes:
+
+```ts
+const api = Bun.serve({
+  ...createApp({ routes: [orders, docs({ info, tags: { orders: "Orders" } })] }),
+  port: 3000,
+});
+
+const admin = Bun.serve({
+  ...createApp({ routes: [users, docs({ info: adminInfo, tags: { users: "Users" } })] }),
+  port: 3001,
+});
+```
 
 ## Operation ids
 
@@ -210,18 +225,37 @@ A status nothing describes keeps its reason phrase — `Not Found`,
 
 Every failure reaches the application's `onError` hooks — a thrown
 `HttpError`, a validation or body failure, a `404`, a `405`, a rate limit's
-refusal — so one hook answers all of them in your format:
+refusal, and an error nothing expected — so one hook answers all of them in
+your format:
 
 ```ts
-const inOurFormat = hook.onError(({ error }) => {
-  if (!(error instanceof HttpError)) return undefined;
+import type { ErrorBody } from "@tetsujs/core";
+import { hook, HttpError, reportFailure } from "@tetsujs/core";
 
-  const { status, error: code, ...rest } = error.body as ErrorBody;
+const inOurFormat = hook.onError((ctx) => {
+  const { error } = ctx;
 
-  return Response.json({ code, ...rest }, { status });
+  if (error instanceof HttpError) {
+    const { status, error: code, ...rest } = error.body as ErrorBody;
+
+    return Response.json({ code, ...rest }, { status });
+  }
+
+  reportFailure(ctx, "unhandled", error);
+
+  return Response.json(
+    { code: "INTERNAL_SERVER_ERROR", message: "Internal Server Error" },
+    { status: 500 },
+  );
 });
 ```
 
+An error the hook answers is one nothing else reports: `reportError` hears
+of a failure only when no `onError` hook answered it. So the hook that
+answers the unexpected ones — a database gone, a `TypeError` — reports them
+itself; left out, they answer in your format and never reach the error
+tracker.
+
 The document is generated from the routes, not from that hook, so it is
 told the same format with `errors`:
 
@@ -269,16 +303,19 @@ code: (schema) => {
 
 The hook and `errors` describe one format in two places — the core knows
 nothing about documents, and a function cannot be read for the shape it
-returns — so keep a test that holds them together: provoke a failure and
-check its body against the document, with the JSON Schema validator of
-your choice.
+returns — so keep a test that holds them together: provoke the failures,
+the unexpected one included, and check each against the document with
+[`assertDescribed`](#testing-against-the-document):
 
 ```ts
-test("a validation failure is what the document says", async () => {
-  const res = await request("/items", { method: "POST", body: "{}" });
-  const schema = document.components?.schemas?.ValidationFailed;
-
-  expect(validator.validate(schema, await res.json())).toBe(true);
+const boom = route({ method: "GET", path: "/boom", handler: () => { throw new Error("boom"); } });
+const app = createApp({ hooks: { onError: [inOurFormat] }, routes: [api, boom] });
+const request = serve(app);
+const { document } = openapi(app, { info, errors });
+
+test("failures are what the document says", async () => {
+  await assertDescribed(document, "POST /items", await request("/items", { method: "POST", body: "{}" }));
+  await assertDescribed(document, "GET /boom", await request("/boom"));
 });
 ```
 
@@ -418,3 +455,11 @@ gap is reported instead of failing the startup:
 This happens with a validator that does not emit JSON Schema, a schema
 whose conversion throws, and two routes that map to the same OpenAPI path
 (`/files/*` and `/files/:wildcard` are both `/files/{wildcard}`).
+
+It also happens with a recursive or named schema. A schema is embedded as
+the validator emits it, and the references inside it — `#` for its own
+root, `#/$defs/…` for a definition next to it — resolve against the
+document's root once embedded, where they lead nowhere. Zod's recursive
+getters and `.meta({ id })`, ArkType's scopes and Valibot's `lazy` emit
+them; TypeBox's `Type.Cyclic` names itself with `$id` and is described as
+it is.

package/dist/src/document.d.ts

@@ -42,6 +42,7 @@ export type ContentMap = Record<string, {
 /** A header a response carries. */
 export interface HeaderObject {
     readonly description?: string;
+    readonly required?: boolean;
     readonly schema: JsonSchema;
 }
 /** One response of an operation. */

package/dist/src/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,eAAe,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA2G1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,eAAe,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA2G1E"}

package/dist/src/index.js

@@ -373,8 +373,8 @@ function operationOf(entry, options, components, envelopes, ids, warn) {
   };
 }
 function declareEnvelopes(entry, envelopes) {
-  for (const [status, schema] of declaredResponses(entry)) {
-    const described = schema === null ? undefined : emitted(schema, "", () => {});
+  for (const [status, { body }] of declaredResponses(entry)) {
+    const described = body === null ? undefined : emitted(body, "", () => {});
     const code = envelopes.format.code;
     for (const branch of described ? branchesOf(described, code) : []) {
       const found = code(branch);
@@ -390,9 +390,62 @@ function declaredResponses(entry) {
     return [];
   }
   if ("~standard" in response) {
-    return [["200", response]];
+    return [["200", { body: response }]];
   }
-  return Object.entries(response);
+  return Object.entries(response).map(([status, value]) => [
+    status,
+    asDeclared(value)
+  ]);
+}
+function asDeclared(value) {
+  if (value === null || "~standard" in value) {
+    return { body: value };
+  }
+  return {
+    body: value.body ?? null,
+    ...value.headers === undefined ? {} : { headers: value.headers },
+    ...value.cookies === undefined ? {} : { cookies: value.cookies }
+  };
+}
+function declaredHeaders(declared, warn) {
+  const headers = {};
+  const [properties, required] = shapeOf2(declared.headers, "a response's headers", warn);
+  for (const [name, property] of Object.entries(properties)) {
+    const { description, ...schema } = property;
+    headers[name] = {
+      ...typeof description === "string" ? { description } : {},
+      ...required.has(name) ? { required: true } : {},
+      schema
+    };
+  }
+  const cookies = setCookie(declared.cookies, warn);
+  if (cookies) {
+    headers["set-cookie"] = cookies;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function setCookie(schema, warn) {
+  const [properties, required] = shapeOf2(schema, "a response's cookies", warn);
+  const names = Object.keys(properties);
+  if (names.length === 0) {
+    return;
+  }
+  const lines = names.map((name) => {
+    const description = properties[name]?.["description"];
+    return typeof description === "string" ? `- \`${name}\`: ${description}` : `- \`${name}\``;
+  });
+  return {
+    description: ["Sets these cookies:", "", ...lines].join(`
+`),
+    ...required.size > 0 ? { required: true } : {},
+    schema: { type: "string" }
+  };
+}
+function shapeOf2(schema, subject, warn) {
+  const described = schema ? emitted(schema, subject, warn, "input") : undefined;
+  const properties = described?.properties ?? {};
+  const required = new Set(Array.isArray(described?.required) ? described.required : []);
+  return [properties, required];
 }
 function branchesFor(schema, status, envelopes, warn) {
   return branchesOf(schema, envelopes.format.code).map((branch) => {
@@ -463,7 +516,7 @@ function derivedId(entry) {
 }
 function requestBody(entry, warn) {
   const declared = entry.def.schema?.body;
-  const bodyType = entry.def.bodyType ?? (declared ? "json" : undefined);
+  const bodyType = entry.def.bodyType ?? (declared || entry.def.rawBody ? "json" : undefined);
   if (!bodyType) {
     return;
   }
@@ -508,15 +561,18 @@ function responses(entry, options, contributed, components, envelopes, warn) {
   const add = (status, answer) => {
     answers.set(status, [...answers.get(status) ?? [], answer]);
   };
-  for (const [status, schema] of declaredResponses(entry)) {
-    const described = schema === null ? undefined : emitted(schema, "a response", warn);
+  const declared = declaredResponses(entry);
+  for (const [status, { body, ...rest }] of declared) {
+    const described = body === null ? undefined : emitted(body, "a response", warn);
+    const headers = declaredHeaders({ body, ...rest }, warn);
     add(status, {
       placeholder: describeStatus(status),
       said: described ? wordsOf(described, envelopes) : [],
-      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : []
+      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : [],
+      ...headers === undefined ? {} : { headers }
     });
   }
-  if (![...answers.keys()].some((status) => status.startsWith("2"))) {
+  if (declared.length === 0) {
     add("200", { placeholder: "Successful response", said: [], schemas: [] });
   }
   for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
@@ -541,7 +597,7 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     const ref = error === undefined ? components.ref(failureName(status), described) : envelopes.ref(status, error, described, warn);
     return ref;
   };
-  if (schema?.params || schema?.query || schema?.headers || schema?.body) {
+  if (schema?.params || schema?.query || schema?.headers || schema?.cookies || schema?.body) {
     found.push([
       options.validationStatus,
       {
@@ -587,7 +643,7 @@ function failures(entry, options, contributed, components, envelopes, warn) {
       }
     ]);
   }
-  if (schema?.body || entry.def.bodyType) {
+  if (schema?.body || entry.def.bodyType || entry.def.rawBody) {
     const unparsable = parseFailure(entry.def.bodyType);
     if (unparsable) {
       found.push([
@@ -745,6 +801,63 @@ function capitalize(value) {
 function lowerFirst(value) {
   return value.charAt(0).toLowerCase() + value.slice(1);
 }
+
+// packages/openapi/src/refs.ts
+var data = new Set(["const", "default", "enum", "example", "examples"]);
+function unresolvedRefs(node, document) {
+  const unresolved = new Set;
+  const visited = new Map;
+  const pending = [[node, document]];
+  for (let next = pending.pop();next; next = pending.pop()) {
+    const [value, base] = next;
+    if (typeof value !== "object" || value === null) {
+      continue;
+    }
+    const bases = visited.get(value) ?? new Set;
+    if (bases.has(base)) {
+      continue;
+    }
+    visited.set(value, bases.add(base));
+    const schema = value;
+    const resource = !Array.isArray(value) && typeof schema["$id"] === "string" ? schema : base;
+    const ref = Array.isArray(value) ? undefined : schema["$ref"];
+    if (typeof ref === "string" && ref.startsWith("#") && !resolves(ref.slice(1), resource, document)) {
+      unresolved.add(ref);
+    }
+    const children = Object.entries(schema).filter(([keyword]) => Array.isArray(value) || !data.has(keyword));
+    for (let index = children.length - 1;index >= 0; index -= 1) {
+      pending.push([children[index]?.[1], resource]);
+    }
+  }
+  return [...unresolved];
+}
+function resolves(fragment, base, document) {
+  if (fragment === "") {
+    return base !== document;
+  }
+  if (!fragment.startsWith("/")) {
+    return true;
+  }
+  let target = base;
+  for (const token of fragment.slice(1).split("/")) {
+    if (typeof target !== "object" || target === null) {
+      return false;
+    }
+    const key = decoded(token);
+    if (key === undefined || !Object.hasOwn(target, key)) {
+      return false;
+    }
+    target = target[key];
+  }
+  return typeof target === "object" && target !== null || typeof target === "boolean";
+}
+function decoded(token) {
+  try {
+    return decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~");
+  } catch {
+    return;
+  }
+}
 // packages/openapi/src/controller.ts
 import { onMount, route } from "@tetsujs/core";
 
@@ -787,7 +900,7 @@ function docsPage(options) {
     "<body>",
     body(options.ui, url),
     `<script src="${escapeHtml(assets.script)}"${verified(assets.integrity?.script)}></script>`,
-    bootstrap(options.ui, url),
+    bootstrap(options.ui),
     "</body>",
     "</html>"
   ].filter(Boolean).join(`
@@ -800,15 +913,16 @@ function body(ui, url) {
   if (ui === "redoc") {
     return `<redoc spec-url="${url}"></redoc>`;
   }
-  return '<div id="swagger-ui"></div>';
+  return `<div id="swagger-ui" data-url="${url}"></div>`;
 }
-function bootstrap(ui, url) {
+function bootstrap(ui) {
   if (ui !== "swagger-ui") {
     return "";
   }
   return [
     "<script>",
-    `SwaggerUIBundle({ url: "${url}", dom_id: "#swagger-ui" });`,
+    'const root = document.getElementById("swagger-ui");',
+    'SwaggerUIBundle({ url: root.dataset.url, dom_id: "#swagger-ui" });',
     "</script>"
   ].join(`
 `);
@@ -938,17 +1052,36 @@ function openapi(app, options) {
     };
   }
   const tags = options.tags ? tagsOf(options.tags, used, warnings) : undefined;
-  return {
-    document: {
-      openapi: "3.1.0",
-      info: options.info,
-      ...options.servers ? { servers: options.servers } : {},
-      ...tags ? { tags } : {},
-      paths,
-      ...componentsOf(schemes, components.schemas)
-    },
-    warnings
+  const document = {
+    openapi: "3.1.0",
+    info: options.info,
+    ...options.servers ? { servers: options.servers } : {},
+    ...tags ? { tags } : {},
+    paths,
+    ...componentsOf(schemes, components.schemas)
   };
+  refsOf(document, occupied, warnings);
+  return { document, warnings };
+}
+function refsOf(document, routes, warnings) {
+  const unresolved = (ref) => `refers to "${ref}", which is no schema in the document: references are embedded as they are, and resolve against the document's root`;
+  for (const [template, item] of Object.entries(document.paths)) {
+    for (const [method, operation] of Object.entries(item)) {
+      const route = routes.get(`${method} ${template}`) ?? "";
+      for (const ref of unresolvedRefs(operation, document)) {
+        warnings.push({ route, message: `a schema ${unresolved(ref)}` });
+      }
+    }
+  }
+  const schemas = document.components?.schemas ?? {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    for (const ref of unresolvedRefs(schema, document)) {
+      warnings.push({
+        route: "",
+        message: `components/schemas/${name} ${unresolved(ref)}`
+      });
+    }
+  }
 }
 function tagsOf(described, used, warnings) {
   const tags = Object.entries(described).map(([name, description]) => ({ name, description }));
@@ -988,5 +1121,5 @@ export {
   secured
 };
 
-//# debugId=3A3B60517CA111D464756E2164756E21
+//# debugId=A9BC9A29B6C6C1DA64756E2164756E21
 //# sourceMappingURL=index.js.map