@enzopita/adonisjs-openapi 0.1.0 → 0.2.1

package/README.md

@@ -7,8 +7,13 @@ Generate an OpenAPI 3.1 document from an AdonisJS 7 app, with no annotations. Th
 | Paths and operations                | Named routes from the router                                                                   |
 | Request body, query and path params | The VineJS validator passed to `request.validateUsing()` (formats, bounds and enums included)  |
 | Responses                           | The return type of the controller method, such as `serialize(UserTransformer.transform(user))` |
+| Status codes                        | Response helpers such as `response.created()`, plus `@throws` tags in the doc comment          |
+| `summary`, `description`, `tags`    | The doc comment on the controller method and its class                                         |
+| Named schemas                       | The transformer types `node ace codegen` writes to `.adonisjs/client/data.d.ts`                |
 | `422` response                      | Added to every route that validates its input                                                  |
-| `security`                          | Named middleware on the route, mapped in the config                                            |
+| `401` response and `security`       | Named middleware on the route, mapped in the config                                            |
+
+Controllers, validators and transformers import nothing from this package. Everything it reads is code an AdonisJS app already has, or a doc comment.
 
 ## Install
 
@@ -16,7 +21,7 @@ Generate an OpenAPI 3.1 document from an AdonisJS 7 app, with no annotations. Th
 node ace add @enzopita/adonisjs-openapi
 ```
 
-The command installs the package, registers its ace command in `adonisrc.ts`, and creates `config/openapi.ts`. The package needs `@adonisjs/assembler`, which every AdonisJS app has as a dev dependency.
+The command installs the package and creates `config/openapi.ts`. In `adonisrc.ts`, it registers the ace command and the build hook that writes the document during `node ace build`, and adds the document to `metaFiles`. The package needs `@adonisjs/assembler`, which every AdonisJS app has as a dev dependency.
 
 ## Generate the document
 
@@ -34,8 +39,13 @@ import { defineConfig } from '@enzopita/adonisjs-openapi'
 
 export default defineConfig({
   output: 'openapi.json',
-  info: { title: 'Acme API', version: '1.0.0' },
+  info: {
+    title: 'Acme API',
+    version: '1.0.0',
+    license: { name: 'MIT', identifier: 'MIT' },
+  },
   servers: [{ url: 'https://api.acme.test' }],
+  tags: [{ name: 'Users', description: 'Public user profiles' }],
   routes: { except: ['admin.'] },
   securitySchemes: {
     accessToken: { type: 'http', scheme: 'bearer' },
@@ -47,11 +57,203 @@ export default defineConfig({
 ```
 
 - `routes` takes `only` or `except`, with the same matchers as Tuyau's `generateRegistry()`: a substring, a regular expression, or a function of the route name.
-- `middlewareSecurity` maps a named middleware, such as `middleware.auth()`, to a key of `securitySchemes`.
+- `info` is the OpenAPI Info Object: `title` and `version`, and optionally `summary`, `description`, `termsOfService`, `contact` and `license`.
+- `tags` is copied to the document's top-level `tags`. Use it to describe the tags operations use and to set their order.
+- `middlewareSecurity` maps a named middleware, such as `middleware.auth()`, to a key of `securitySchemes`. Routes behind it get the scheme in `security` and a `401` response. A route behind several mapped middleware, such as `middleware.auth()` and `middleware.tenant()`, requires all their schemes together: they share one Security Requirement Object.
+
+## Serve a docs page
+
+`openapiRoutes()` registers two routes: a page that renders the document with [Scalar](https://github.com/scalar/scalar), and the document itself.
+
+```ts
+// start/routes.ts
+import { middleware } from '#start/kernel'
+import { openapiRoutes } from '@enzopita/adonisjs-openapi/routes'
+
+openapiRoutes().use(middleware.auth({ guards: ['basic'] }))
+```
+
+| Route                    | Name               | Response                            |
+| ------------------------ | ------------------ | ----------------------------------- |
+| `GET /docs`              | `openapi.ui`       | The HTML page                       |
+| `GET /docs/openapi.json` | `openapi.document` | The document, as `application/json` |
+
+`openapiRoutes()` returns the route group, so `.use()`, `.domain()`, `.prefix()` and `.as()` work on it. `.as('admin')` names the routes `admin.openapi.ui` and `admin.openapi.document`.
+
+The page loads the document from a URL relative to the page, so it keeps working behind a proxy that serves the app under a path prefix. The generator leaves both routes out of the document, as it does every closure route. Tuyau keeps named closure routes, so they appear in its client registry. To leave them out, exclude them where `adonisrc.ts` calls `generateRegistry()`:
+
+```ts
+generateRegistry({ routes: { except: [/^openapi\./] } })
+```
+
+### Turn the page on or off
+
+The routes exist only where `openapiRoutes()` runs. To serve the page outside production only:
+
+```ts
+import app from '@adonisjs/core/services/app'
+
+if (!app.inProduction) openapiRoutes()
+```
+
+To turn it on with an environment variable, declare `OPENAPI_DOCS: Env.schema.boolean.optional()` in `start/env.ts`, then:
+
+```ts
+import env from '#start/env'
+
+if (env.get('OPENAPI_DOCS')) openapiRoutes().use(middleware.auth({ guards: ['basic'] }))
+```
+
+To remove the page, delete the call. No other file of the app imports `@enzopita/adonisjs-openapi/routes`.
+
+### Options
+
+| Option      | Default                                    | Description                                                                                                                                      |
+| ----------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`    | `'/docs'`                                  | Path of the page. The document is at `<prefix>/openapi.json`.                                                                                    |
+| `ui`        | `'scalar'`                                 | `'scalar'`, `'swagger-ui'`, `'redoc'`, or a function that returns the page HTML.                                                                 |
+| `uiOptions` | `{}`                                       | Passed as JSON to the UI's init call: `Scalar.createApiReference()`, `SwaggerUIBundle()` or Redoc's `init()`.                                    |
+| `cdn`       | jsDelivr, see below                        | `{ script }` for Scalar and Redoc, `{ script, style }` for Swagger UI. Replaces the default URLs, for example to serve the files from `public/`. |
+| `title`     | `info.title` from the config               | The page `<title>`.                                                                                                                              |
+| `source`    | `'file'` in production, `'live'` otherwise | `'live'` generates the document on each request. `'file'` serves the file `node ace openapi:generate` wrote.                                     |
+| `file`      | `output` from the config                   | The file `source: 'file'` reads, relative to the app root.                                                                                       |
+| `transform` | none                                       | `(document, ctx) => document`, applied to each response. It receives a copy, so it can edit the document in place.                               |
+
+The default assets come from jsDelivr, pinned to a major version:
+
+| UI           | Files                                                                           |
+| ------------ | ------------------------------------------------------------------------------- |
+| `scalar`     | `@scalar/api-reference@1/dist/browser/standalone.js`                            |
+| `swagger-ui` | `swagger-ui-dist@5/swagger-ui-bundle.js` and `swagger-ui-dist@5/swagger-ui.css` |
+| `redoc`      | `redoc@3/bundles/redoc.standalone.js`                                           |
+
+A function `ui` receives `title`, `documentUrl` and `nonce`, and returns the whole page. `documentUrl` is relative to the page. `nonce` is set when Shield's CSP is enabled.
+
+```ts
+openapiRoutes({
+  ui: ({ title, documentUrl }) => `<!doctype html>
+<title>${title}</title>
+<redoc spec-url="${documentUrl}"></redoc>
+<script type="module" src="https://cdn.redoc.ly/redoc/v3.x/bundles/redoc.standalone.js"></script>`,
+})
+```
+
+`transform` can fill in what the config cannot know, such as the host a request came to:
+
+```ts
+openapiRoutes({
+  transform: (document, { request }) => ({
+    ...document,
+    servers: [{ url: `${request.protocol()}://${request.host()}` }],
+  }),
+})
+```
+
+### Where the document comes from
+
+With `source: 'live'`, each request runs the generator in the app process. The page always matches the routes, with no command to run. The generator reads the TypeScript sources and needs `@adonisjs/assembler`, which the dev server and `node ace test` have.
+
+With `source: 'file'`, the route serves the file `node ace openapi:generate` wrote. In production, the route reads the file once and keeps it in memory. Elsewhere, it reads the file on each request. When the file is missing, the route responds with a `500` error that names `node ace openapi:generate` and the build hook.
+
+### Ship the document with the build
+
+A `node ace build` output has no TypeScript sources, and a production install has no `@adonisjs/assembler`. In production, the page serves the file instead. `node ace add` registers what writes the file and copies it into `build/`:
+
+```ts
+// adonisrc.ts
+export default defineConfig({
+  metaFiles: [{ pattern: 'openapi.json', reloadServer: false }],
+  hooks: {
+    buildStarting: [() => import('@enzopita/adonisjs-openapi/build_hook')],
+  },
+})
+```
+
+The hook runs `node ace openapi:generate` before `node ace build` compiles the app, and `metaFiles` copies `openapi.json` into `build/`. If you change `output` in the config, change the `metaFiles` pattern to match.
+
+Without the hook, you can commit the generated file and keep it in `metaFiles`. Run `node ace openapi:generate` again each time the routes change.
+
+### Protect the page
+
+A browser opens the page with a plain navigation. It sends cookies and HTTP basic credentials, but it has no way to add an `Authorization: Bearer` header. A guard that reads a bearer token, such as the access tokens guard, answers `401` to every visit from a browser. Use a guard that the browser can satisfy:
+
+- The basic auth guard. On a `401`, the browser shows its own login prompt. Serve the page over HTTPS, because basic auth sends the password with every request.
+- The session guard, if the app already has a login page.
+
+The basic auth guard needs an entry in `config/auth.ts`:
+
+```ts
+import { basicAuthGuard, basicAuthUserProvider } from '@adonisjs/auth/basic_auth'
+
+const authConfig = defineConfig({
+  guards: {
+    basic: basicAuthGuard({
+      provider: basicAuthUserProvider({ model: () => import('#models/user') }),
+    }),
+  },
+})
+```
+
+### Content Security Policy
+
+Shield's CSP is off in a new app. If you turn it on, the page needs the directives below on top of `defaultSrc: ["'self'"]`. The page sets Shield's nonce on its scripts, so `@nonce` allows them. Each UI loads in Chromium with no CSP violation under these directives.
+
+| UI           | Directives                                                                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `scalar`     | `scriptSrc: ['@nonce']`, `styleSrc: ["'unsafe-inline'"]`, `fontSrc: ['https://fonts.scalar.com']`                  |
+| `swagger-ui` | `scriptSrc: ['@nonce']`, `styleSrc: ['https://cdn.jsdelivr.net']`, `imgSrc: ['data:']`                             |
+| `redoc`      | `scriptSrc: ['@nonce']`, `styleSrc: ["'unsafe-inline'"]`, `fontSrc: ['data:']`, `imgSrc: ['https://cdn.redoc.ly']` |
+
+Shield applies one policy to every route, so these directives apply to the whole app. A custom `cdn` replaces `https://cdn.jsdelivr.net` with the host it points to.
+
+## Document an operation
+
+The generator reads the doc comment on the controller method, the same way the NestJS Swagger plugin does:
+
+```ts
+/**
+ * @tags Users
+ */
+export default class UsersController {
+  /**
+   * Show a user
+   *
+   * Looks the user up by its numeric id.
+   *
+   * @throws {404} User not found
+   */
+  async show({ request, serialize }: HttpContext) {
+    const { params } = await request.validateUsing(showUserValidator)
+
+    return serialize(UserTransformer.transform(await User.findOrFail(params.id)))
+  }
+}
+```
+
+- The first paragraph is the `summary`. The next paragraphs and `@remarks` are the `description`.
+- `@deprecated` marks the operation as deprecated.
+- `@tags Users, Admin` sets the operation tags. On the class, it applies to every method. A method's own `@tags` replaces the class tags. Without either, the tag is the first segment of the route name.
+- `@throws {404} User not found` adds a `404` response with that description. Without a description, the standard status text is used. Tags whose type is not a three-digit code are ignored.
+
+## Status codes
+
+A response comes from each status code the handler can return:
+
+- `return serialize(...)` or a plain object is a `200`.
+- `return response.created(await serialize(...))` is a `201` with the serialized body. Every `HttpResponse` helper that sets a 2xx, 4xx or 5xx status works this way, such as `noContent()`, `accepted()` or `notFound(body)`. This uses the same types Tuyau adds to `HttpResponse`, and works without Tuyau too.
+- `204`, `205` and `304` responses, and helpers called without a body, have no `content`.
+- A `@throws` tag adds its status code when the return type has not.
+- Routes that validate their input get a `422`. Routes behind a middleware mapped in `middlewareSecurity` get a `401`.
+
+## Named schemas
+
+When `.adonisjs/client/data.d.ts` exists, every type in its `Data` namespace becomes a schema in `components.schemas`, named by its path below `Data`: `User`, or `Admin.User` for a nested namespace. Responses reference them with `$ref`, including items of a collection and transformers nested in an object passed to `serialize()`. The `422` body is the `ValidationError` schema.
+
+`node ace codegen` writes that file when `indexEntities()` in `adonisrc.ts` has transformers enabled. Without it, schemas are inlined.
 
 ## How types become schemas
 
-- A route must have a name and a controller handler. Closure routes are skipped, as they are in Tuyau.
+- A route must have a name and a controller handler. Closure routes are skipped.
 - On `GET` routes, the validator fields become query parameters. On other methods they become the body, and the validator's `query` and `params` objects become query and path parameters.
 - A body with a `vine.file()` field is sent as `multipart/form-data`.
 - When VineJS cannot describe a field (a file, a custom rule), the generator uses the field's TypeScript type.
@@ -60,6 +262,7 @@ export default defineConfig({
 
 ## Limitations
 
-- Schemas are inlined. Transformers do not become named components yet.
-- Operations have no `summary` or `description` yet.
-- Status codes other than `200` and `422` come only from return types that carry a `__status`, which no AdonisJS 7.6 API produces yet.
+- A status code set with `response.status(201)` is not detected, because the return type does not carry it. Return a helper such as `response.created(body)` instead.
+- A thrown exception has no return type either. Add a `@throws` tag for each status code it can produce, such as the `404` of `findOrFail()`.
+- A nested transformer is matched to its named schema by shape. Two transformers with the same output share the first schema name.
+- Every type in `Data` is written to `components.schemas`, even if no route returns it.

package/build/configure.js

@@ -4,5 +4,13 @@ export async function configure(command) {
     await codemods.makeUsingStub(stubsRoot, 'config/openapi.stub', {});
     await codemods.updateRcFile(rcFile => {
         rcFile.addCommand('@enzopita/adonisjs-openapi/commands');
+        rcFile.addAssemblerHook('buildStarting', '@enzopita/adonisjs-openapi/build_hook');
+        rcFile.addMetaFile('openapi.json');
     });
+    command.ui
+        .instructions()
+        .heading('To serve the docs page, register its routes in start/routes.ts')
+        .add(`import { openapiRoutes } from '@enzopita/adonisjs-openapi/routes'`)
+        .add(`openapiRoutes()`)
+        .render();
 }

package/build/index.d.ts

@@ -1,4 +1,9 @@
+import type { generateDocument as generate } from './src/generate.ts';
 export { configure } from './configure.ts';
 export { defineConfig } from './src/define_config.ts';
-export { generateDocument } from './src/generate.ts';
 export { stubsRoot } from './stubs/main.ts';
+/**
+ * Loads the generator on call. `config/openapi.ts` imports this entry on every boot, and the
+ * generator pulls in the TypeScript compiler, and the assembler that a production install leaves out.
+ */
+export declare function generateDocument(...args: Parameters<typeof generate>): Promise<import("./src/generate.ts").GeneratedDocument>;

package/build/index.js

@@ -1,4 +1,11 @@
 export { configure } from "./configure.js";
 export { defineConfig } from "./src/define_config.js";
-export { generateDocument } from "./src/generate.js";
 export { stubsRoot } from "./stubs/main.js";
+/**
+ * Loads the generator on call. `config/openapi.ts` imports this entry on every boot, and the
+ * generator pulls in the TypeScript compiler, and the assembler that a production install leaves out.
+ */
+export async function generateDocument(...args) {
+    const { generateDocument: run } = await import("./src/generate.js");
+    return run(...args);
+}

package/build/src/build_hook.d.ts

@@ -0,0 +1,7 @@
+import type { Bundler } from '@adonisjs/assembler';
+/**
+ * Runs before `node ace build` compiles the app and copies the meta files, so the
+ * document lands in the build folder when its path is listed in `metaFiles`.
+ */
+declare const generateOnBuild: (bundler: Bundler) => void | PromiseLike<void>;
+export default generateOnBuild;

package/build/src/build_hook.js

@@ -0,0 +1,18 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { hooks } from '@adonisjs/core/app';
+/**
+ * Runs before `node ace build` compiles the app and copies the meta files, so the
+ * document lands in the build folder when its path is listed in `metaFiles`.
+ */
+const generateOnBuild = hooks.buildStarting(async (bundler) => {
+    bundler.ui.logger.info('generating the OpenAPI document', { suffix: 'openapi:generate' });
+    const child = spawn(process.execPath, ['ace', 'openapi:generate'], {
+        cwd: bundler.cwdPath,
+        stdio: 'inherit',
+    });
+    const [code] = await once(child, 'close');
+    if (code !== 0)
+        throw new Error(`"node ace openapi:generate" exited with code ${code}`);
+});
+export default generateOnBuild;

package/build/src/collect_routes.js

@@ -31,11 +31,13 @@ export async function collectRoutes(appRoot, router, config) {
         const names = [...route.middleware.all()].flatMap(entry => 'name' in entry && entry.name ? [entry.name] : []);
         middlewareByRoute.set(`${route.domain}:${route.pattern}:${route.methods.join(',')}`, names);
     }
-    // Round-tripped through JSON like the dev server and `node ace codegen` do, which drops closure handlers.
-    const serialized = JSON.parse(JSON.stringify(live));
+    // A closure has no types to read, and the scanner keeps it when it is named.
+    const controllerRoutes = Object.values(live).map(routes => routes.filter(route => !(route.handler instanceof Function)));
+    // Round-tripped through JSON like the dev server and `node ace codegen` do.
+    const serialized = JSON.parse(JSON.stringify(controllerRoutes));
     const scanner = new RoutesScanner(appRoot, []);
     scanner.filter(route => isIncluded(route.name ?? '', config.routes));
-    for (const routes of Object.values(serialized))
+    for (const routes of serialized)
         await scanner.scan(routes);
     return scanner.getScannedRoutes().map(route => {
         const pattern = toOpenApiPath(route.pattern);
@@ -55,6 +57,10 @@ export async function collectRoutes(appRoot, router, config) {
                 specifier: validator.import.specifier,
                 exportName: validator.import.value,
             },
+            controller: route.controller && {
+                path: route.controller.path,
+                method: route.controller.method,
+            },
         };
     });
 }

package/build/src/define_config.js

@@ -6,6 +6,7 @@ export function defineConfig(config = {}) {
         output: 'openapi.json',
         info: { title: 'API', version: '1.0.0' },
         servers: [],
+        tags: [],
         routes: {},
         securitySchemes: {},
         middlewareSecurity: {},

package/build/src/docs/html.d.ts

@@ -0,0 +1,8 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+export declare function escapeHtml(text: string): string;
+/**
+ * `<` is escaped so that a `</script>` inside a string cannot close the script it is embedded in.
+ */
+export declare function scriptJson(value: UiOptions | string): string;
+export declare function script(page: DocsPage, attributes: string, code?: string): string;
+export declare function htmlPage(page: DocsPage, head: string[], body: string[]): string;

package/build/src/docs/html.js

@@ -0,0 +1,37 @@
+const ENTITIES = new Map([
+    ['&', '&'],
+    ['<', '&lt;'],
+    ['>', '&gt;'],
+    ['"', '&quot;'],
+    ["'", '&#39;'],
+]);
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, char => ENTITIES.get(char) ?? char);
+}
+/**
+ * `<` is escaped so that a `</script>` inside a string cannot close the script it is embedded in.
+ */
+export function scriptJson(value) {
+    return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+export function script(page, attributes, code = '') {
+    const nonce = page.nonce ? ` nonce="${escapeHtml(page.nonce)}"` : '';
+    return `<script${nonce}${attributes}>${code}</script>`;
+}
+export function htmlPage(page, head, body) {
+    return [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8" />',
+        '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+        `<title>${escapeHtml(page.title)}</title>`,
+        ...head,
+        '</head>',
+        '<body>',
+        ...body,
+        '</body>',
+        '</html>',
+        '',
+    ].join('\n');
+}

package/build/src/docs/redoc.d.ts

@@ -0,0 +1,14 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+declare const cdn: {
+    script: string;
+};
+export declare const redoc: {
+    cdn: {
+        script: string;
+    };
+    /**
+     * Redoc 3 ships its standalone bundle as an ES module, so `init` is imported instead of read from `window`.
+     */
+    render(page: DocsPage, assets: typeof cdn, uiOptions: UiOptions): string;
+};
+export {};

package/build/src/docs/redoc.js

@@ -0,0 +1,17 @@
+import { htmlPage, script, scriptJson } from "./html.js";
+const cdn = {
+    script: 'https://cdn.jsdelivr.net/npm/redoc@3/bundles/redoc.standalone.js',
+};
+export const redoc = {
+    cdn,
+    /**
+     * Redoc 3 ships its standalone bundle as an ES module, so `init` is imported instead of read from `window`.
+     */
+    render(page, assets, uiOptions) {
+        const init = [
+            `import { init } from ${scriptJson(assets.script)}`,
+            `init(${scriptJson(page.documentUrl)}, ${scriptJson(uiOptions)}, document.getElementById('redoc'))`,
+        ].join('\n');
+        return htmlPage(page, [], ['<div id="redoc"></div>', script(page, ' type="module"', init)]);
+    },
+};

package/build/src/docs/routes.d.ts

@@ -0,0 +1,6 @@
+import type { DocsOptions } from '../types.ts';
+/**
+ * Registers the docs page and the document it renders, as closure routes so the
+ * generator leaves them out of the document.
+ */
+export declare function openapiRoutes(options?: DocsOptions): import("@adonisjs/core/http").RouteGroup;

package/build/src/docs/routes.js

@@ -0,0 +1,81 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path/posix';
+import app from '@adonisjs/core/services/app';
+import router from '@adonisjs/core/services/router';
+import { createError } from '@adonisjs/core/exceptions';
+import { defineConfig } from "../define_config.js";
+import { renderPage } from "./ui.js";
+const E_OPENAPI_DOCUMENT_MISSING = createError('Cannot find the OpenAPI document at "%s". Run "node ace openapi:generate", or register the "@enzopita/adonisjs-openapi/build_hook" build hook so "node ace build" writes it', 'E_OPENAPI_DOCUMENT_MISSING', 500);
+function openapiConfig() {
+    return app.config.get('openapi') ?? defineConfig();
+}
+/**
+ * The page is served at `<prefix>` and the document at `<prefix>/openapi.json`, so the
+ * document URL only depends on the last segment of the URL the page was requested with.
+ */
+function documentUrl(pagePath) {
+    return pagePath.endsWith('/') ? 'openapi.json' : `${basename(pagePath)}/openapi.json`;
+}
+/**
+ * Shield sets the nonce when CSP is enabled. This package does not depend on Shield, so its type is not augmented here.
+ */
+function cspNonce(response) {
+    return 'nonce' in response ? String(response.nonce) : undefined;
+}
+async function generateLive() {
+    // Loaded on demand: it pulls in the assembler, a dev dependency that a production install leaves out.
+    const { generateDocument } = await import("../generate.js");
+    const { document } = await generateDocument(app, router, openapiConfig());
+    return document;
+}
+async function readGenerated(file) {
+    const path = app.makePath(file);
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new E_OPENAPI_DOCUMENT_MISSING([app.relativePath(path)], { cause: error });
+        }
+        throw error;
+    }
+}
+function documentSource(options) {
+    const source = options.source ?? (app.inProduction ? 'file' : 'live');
+    if (source === 'live')
+        return generateLive;
+    const file = () => options.file ?? openapiConfig().output;
+    if (!app.inProduction)
+        return () => readGenerated(file());
+    let cached;
+    return async () => (cached ??= await readGenerated(file()));
+}
+/**
+ * Registers the docs page and the document it renders, as closure routes so the
+ * generator leaves them out of the document.
+ */
+export function openapiRoutes(options = {}) {
+    const loadDocument = documentSource(options);
+    return router
+        .group(() => {
+        router
+            .get('/', ({ request, response }) => {
+            const page = renderPage(options, {
+                title: options.title ?? openapiConfig().info.title,
+                documentUrl: documentUrl(request.url()),
+                nonce: cspNonce(response),
+            });
+            response.header('content-type', 'text/html; charset=utf-8');
+            return page;
+        })
+            .as('openapi.ui');
+        router
+            .get('/openapi.json', async (ctx) => {
+            const document = await loadDocument();
+            // A copy, so a transform that edits the document in place cannot leak into the cached one.
+            return options.transform ? options.transform(structuredClone(document), ctx) : document;
+        })
+            .as('openapi.document');
+    })
+        .prefix(options.prefix ?? '/docs');
+}

package/build/src/docs/scalar.d.ts

@@ -0,0 +1,11 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+declare const cdn: {
+    script: string;
+};
+export declare const scalar: {
+    cdn: {
+        script: string;
+    };
+    render(page: DocsPage, assets: typeof cdn, uiOptions: UiOptions): string;
+};
+export {};

package/build/src/docs/scalar.js

@@ -0,0 +1,15 @@
+import { escapeHtml, htmlPage, script, scriptJson } from "./html.js";
+const cdn = {
+    script: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1/dist/browser/standalone.js',
+};
+export const scalar = {
+    cdn,
+    render(page, assets, uiOptions) {
+        const config = scriptJson({ url: page.documentUrl, ...uiOptions });
+        return htmlPage(page, [], [
+            '<div id="app"></div>',
+            script(page, ` src="${escapeHtml(assets.script)}"`),
+            script(page, '', `Scalar.createApiReference('#app', ${config})`),
+        ]);
+    },
+};

package/build/src/docs/swagger_ui.d.ts

@@ -0,0 +1,13 @@
+import type { DocsPage, UiOptions } from '../types.ts';
+declare const cdn: {
+    script: string;
+    style: string;
+};
+export declare const swaggerUi: {
+    cdn: {
+        script: string;
+        style: string;
+    };
+    render(page: DocsPage, assets: typeof cdn, uiOptions: UiOptions): string;
+};
+export {};

package/build/src/docs/swagger_ui.js

@@ -0,0 +1,16 @@
+import { escapeHtml, htmlPage, script, scriptJson } from "./html.js";
+const cdn = {
+    script: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js',
+    style: 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css',
+};
+export const swaggerUi = {
+    cdn,
+    render(page, assets, uiOptions) {
+        const config = scriptJson({ url: page.documentUrl, dom_id: '#swagger-ui', ...uiOptions });
+        return htmlPage(page, [`<link rel="stylesheet" href="${escapeHtml(assets.style)}" />`], [
+            '<div id="swagger-ui"></div>',
+            script(page, ` src="${escapeHtml(assets.script)}"`),
+            script(page, '', `window.ui = SwaggerUIBundle(${config})`),
+        ]);
+    },
+};

package/build/src/docs/ui.d.ts

@@ -0,0 +1,2 @@
+import type { DocsPage, DocsUi } from '../types.ts';
+export declare function renderPage(options: DocsUi, page: DocsPage): string;

package/build/src/docs/ui.js

@@ -0,0 +1,13 @@
+import { redoc } from "./redoc.js";
+import { scalar } from "./scalar.js";
+import { swaggerUi } from "./swagger_ui.js";
+const renderers = { scalar, 'swagger-ui': swaggerUi, redoc };
+function renderBuiltIn(ui, page, cdn, uiOptions) {
+    const renderer = renderers[ui];
+    return renderer.render(page, { ...renderer.cdn, ...cdn }, uiOptions);
+}
+export function renderPage(options, page) {
+    if (options.ui instanceof Function)
+        return options.ui(page);
+    return renderBuiltIn(options.ui ?? 'scalar', page, options.cdn, options.uiOptions ?? {});
+}

package/build/src/generate.js

@@ -50,28 +50,35 @@ async function validatorSchemas(app, routes, warnings) {
     }
     return schemas;
 }
-function responsesFor(route, types, response, warnings) {
+const EMPTY_STATUSES = new Set(['204', '205', '304']);
+const WITHOUT_BODY = ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Void | ts.TypeFlags.Undefined;
+function responsesFor(route, types, response, thrown, secured, warnings) {
     const responses = {};
-    const describe = (code, schema) => {
-        responses[code] = {
-            description: STATUS_CODES[Number(code)] ?? 'Response',
-            content: { 'application/json': { schema } },
-        };
+    const describe = (code, payload) => {
+        const description = STATUS_CODES[Number(code)] ?? 'Response';
+        const empty = !payload || EMPTY_STATUSES.has(code) || payload.flags & WITHOUT_BODY;
+        responses[code] = empty
+            ? { description }
+            : { description, content: { 'application/json': { schema: types.schemas.convert(payload) } } };
     };
     const members = response?.isUnion() ? response.types : response ? [response] : [];
     for (const member of members) {
         const status = types.property(member, '__status');
         const payload = types.property(member, '__response');
         if (status && payload) {
-            describe(status.isNumberLiteral() ? String(status.value) : 'default', types.schemas.convert(payload));
+            describe(status.isNumberLiteral() ? String(status.value) : 'default', payload);
         }
         else if (!(member.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) {
-            describe('200', types.schemas.convert(member));
+            describe('200', member);
         }
     }
+    for (const [code, description] of Object.entries(thrown))
+        responses[code] ??= { description };
     const validationError = route.validator && types.validationError();
-    if (validationError)
-        describe('422', types.schemas.convert(validationError));
+    if (validationError && !responses['422'])
+        describe('422', validationError);
+    if (secured && !responses['401'])
+        describe('401');
     if (!Object.keys(responses).some(code => code.startsWith('2') || code === 'default')) {
         warnings.push(`${route.name}: the handler's return type is unknown, returning serialize(...) makes it typed`);
         responses['200'] = { description: 'OK' };
@@ -108,13 +115,16 @@ export async function generateDocument(app, router, config) {
         const body = readsQueryOnly ? undefined : fields;
         const query = readsQueryOnly ? fields : input?.properties?.query;
         const parameters = parametersFor(route, query, input?.properties?.params);
-        const security = route.middleware.flatMap(name => {
-            const scheme = config.middlewareSecurity[name];
-            return scheme ? [{ [scheme]: [] }] : [];
-        });
+        // Entries of `security` are alternatives, so the schemes a route requires together share one entry.
+        const schemes = route.middleware.flatMap(name => config.middlewareSecurity[name] ?? []);
+        const security = schemes.length
+            ? [Object.fromEntries(schemes.map(scheme => [scheme, []]))]
+            : [];
+        const { responses: thrown, ...docs } = types.docs(route);
         const operation = {
-            tags: [route.name.split('.')[0] ?? route.name],
-            responses: responsesFor(route, types, response, warnings),
+            ...docs,
+            tags: docs.tags ?? [route.name.split('.')[0] ?? route.name],
+            responses: responsesFor(route, types, response, thrown, security.length > 0, warnings),
         };
         if (parameters.length)
             operation.parameters = parameters;
@@ -144,5 +154,7 @@ export async function generateDocument(app, router, config) {
     };
     if (config.servers.length)
         document.servers = config.servers;
+    if (config.tags.length)
+        document.tags = config.tags;
     return { document, warnings };
 }

package/build/src/operation_docs.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+export interface OperationDocs {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: true;
+    /**
+     * Status code to description, from `@throws {404} User not found`.
+     */
+    responses: Record<string, string>;
+}
+export declare function operationDocs(controller: ts.ClassDeclaration, method: ts.MethodDeclaration): OperationDocs;

package/build/src/operation_docs.js

@@ -0,0 +1,51 @@
+import { STATUS_CODES } from 'node:http';
+import ts from 'typescript';
+function jsDoc(node) {
+    return ts.getJSDocCommentsAndTags(node).filter(ts.isJSDoc).at(-1);
+}
+function tagText(tag) {
+    return ts.getTextOfJSDocComment(tag.comment)?.trim() ?? '';
+}
+function tagsOf(doc) {
+    const tag = doc?.tags?.find(candidate => candidate.tagName.text === 'tags');
+    return (tag &&
+        tagText(tag)
+            .split(',')
+            .map(name => name.trim())
+            .filter(Boolean));
+}
+/**
+ * `@throws {404}` parses as a JSDoc type expression holding the literal type `404`.
+ */
+function thrownStatus(tag) {
+    const type = ts.isJSDocThrowsTag(tag) ? tag.typeExpression?.type : undefined;
+    if (!type || !ts.isLiteralTypeNode(type) || !ts.isNumericLiteral(type.literal))
+        return undefined;
+    return /^\d{3}$/.test(type.literal.text) ? type.literal.text : undefined;
+}
+export function operationDocs(controller, method) {
+    const doc = jsDoc(method);
+    const responses = {};
+    const tags = tagsOf(doc) ?? tagsOf(jsDoc(controller));
+    let deprecated = false;
+    const [summary, ...paragraphs] = (ts.getTextOfJSDocComment(doc?.comment) ?? '')
+        .split(/\n\s*\n/)
+        .map(paragraph => paragraph.trim())
+        .filter(Boolean);
+    for (const tag of doc?.tags ?? []) {
+        const status = thrownStatus(tag);
+        if (status)
+            responses[status] = tagText(tag) || (STATUS_CODES[Number(status)] ?? status);
+        else if (ts.isJSDocDeprecatedTag(tag))
+            deprecated = true;
+        else if (tag.tagName.text === 'remarks' && tagText(tag))
+            paragraphs.push(tagText(tag));
+    }
+    return {
+        ...(summary && { summary }),
+        ...(paragraphs.length > 0 && { description: paragraphs.join('\n\n') }),
+        ...(tags?.length && { tags }),
+        ...(deprecated && { deprecated: true }),
+        responses,
+    };
+}

package/build/src/route_types.d.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript';
+import { type OperationDocs } from './operation_docs.ts';
 import { TypeToSchema } from './type_to_schema.ts';
 import type { RouteOperation } from './types.ts';
 /**
@@ -21,5 +22,9 @@ export declare class RouteTypes {
         response: ts.Type | undefined;
     };
     validationError(): ts.Type | undefined;
+    /**
+     * The doc comments on the handler, read from the controller class the file exports by default.
+     */
+    docs({ controller }: RouteOperation): OperationDocs;
     property(type: ts.Type, name: string): ts.Type | undefined;
 }

package/build/src/route_types.js

@@ -1,6 +1,48 @@
 import ts from 'typescript';
+import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { operationDocs } from "./operation_docs.js";
 import { TypeToSchema } from "./type_to_schema.js";
+/**
+ * The `HttpResponse` helpers that set a status code, as Tuyau types them minus the
+ * informational and redirect ones. Declared here as well so apps without Tuyau get them.
+ */
+const RESPONSE_HELPERS = {
+    ok: 200,
+    json: 200,
+    created: 201,
+    accepted: 202,
+    nonAuthoritativeInformation: 203,
+    noContent: 204,
+    resetContent: 205,
+    partialContent: 206,
+    badRequest: 400,
+    unauthorized: 401,
+    paymentRequired: 402,
+    forbidden: 403,
+    notFound: 404,
+    methodNotAllowed: 405,
+    notAcceptable: 406,
+    proxyAuthenticationRequired: 407,
+    requestTimeout: 408,
+    conflict: 409,
+    gone: 410,
+    lengthRequired: 411,
+    preconditionFailed: 412,
+    requestEntityTooLarge: 413,
+    requestUriTooLong: 414,
+    unsupportedMediaType: 415,
+    requestedRangeNotSatisfiable: 416,
+    expectationFailed: 417,
+    unprocessableEntity: 422,
+    tooManyRequests: 429,
+    internalServerError: 500,
+    notImplemented: 501,
+    badGateway: 502,
+    serviceUnavailable: 503,
+    gatewayTimeout: 504,
+    httpVersionNotSupported: 505,
+};
 /**
  * Resolves the request and response types of every route with the app's own
  * tsconfig, through one in-memory module that names them all.
@@ -8,10 +50,12 @@ import { TypeToSchema } from "./type_to_schema.js";
 export class RouteTypes {
     checker;
     schemas;
+    #program;
     #routes;
     #validationError;
     constructor(appRoot, routes) {
         const entryFile = join(appRoot, '.adonisjs/openapi/routes.ts');
+        const dataFile = join(appRoot, '.adonisjs/client/data.d.ts');
         const config = ts.getParsedCommandLineOfConfigFile(join(appRoot, 'tsconfig.json'), {}, {
             ...ts.sys,
             onUnRecoverableConfigFileDiagnostic: diagnostic => {
@@ -30,15 +74,37 @@ export class RouteTypes {
         host.fileExists = fileName => fileName === entryFile || fileExists(fileName);
         // The app's own files carry the module augmentations (container bindings, auth guards) the types depend on.
         const program = ts.createProgram({
-            rootNames: [...config.fileNames, entryFile],
+            rootNames: [...config.fileNames, entryFile, ...(existsSync(dataFile) ? [dataFile] : [])],
             options: { ...config.options, noEmit: true },
             host,
         });
+        this.#program = program;
         this.checker = program.getTypeChecker();
-        this.schemas = new TypeToSchema(this.checker);
         const entry = program.getSourceFile(entryFile);
         this.#routes = entry.statements.find(ts.isInterfaceDeclaration);
         this.#validationError = entry.statements.find(ts.isTypeAliasDeclaration);
+        const validationError = this.validationError();
+        const named = new Map(this.#transformerTypes(program.getSourceFile(dataFile)));
+        if (validationError)
+            named.set(validationError, 'ValidationError');
+        this.schemas = new TypeToSchema(this.checker, named);
+    }
+    /**
+     * The types `node ace codegen` names in `Data`, keyed by their path below it (`Admin.User`).
+     */
+    #transformerTypes(dataFile) {
+        const module = dataFile && this.checker.getSymbolAtLocation(dataFile);
+        const data = module && this.checker.tryGetMemberInModuleExports('Data', module);
+        const walk = (namespace, path) => this.checker.getExportsOfModule(namespace).flatMap(symbol => {
+            if (symbol.name === 'Variants')
+                return [];
+            const name = [...path, symbol.name];
+            const nested = symbol.flags & ts.SymbolFlags.Namespace ? walk(symbol, name) : [];
+            if (!(symbol.flags & ts.SymbolFlags.TypeAlias))
+                return nested;
+            return [[this.checker.getDeclaredTypeOfSymbol(symbol), name.join('.')], ...nested];
+        });
+        return data ? walk(data, []) : [];
     }
     /**
      * The types of one route's `request` and `response` members.
@@ -55,6 +121,22 @@ export class RouteTypes {
     validationError() {
         return this.#validationError && this.checker.getTypeAtLocation(this.#validationError);
     }
+    /**
+     * The doc comments on the handler, read from the controller class the file exports by default.
+     */
+    docs({ controller }) {
+        const file = controller && this.#program.getSourceFile(controller.path);
+        const module = file && this.checker.getSymbolAtLocation(file);
+        const exported = module && this.checker.tryGetMemberInModuleExports('default', module);
+        const symbol = exported && exported.flags & ts.SymbolFlags.Alias
+            ? this.checker.getAliasedSymbol(exported)
+            : exported;
+        const declaration = symbol?.declarations?.find(ts.isClassDeclaration);
+        const method = declaration?.members.find((member) => ts.isMethodDeclaration(member) &&
+            ts.isIdentifier(member.name) &&
+            member.name.text === controller?.method);
+        return declaration && method ? operationDocs(declaration, method) : { responses: {} };
+    }
     property(type, name) {
         const symbol = this.checker.getPropertyOfType(type, name);
         return symbol && this.checker.getTypeOfSymbol(symbol);
@@ -76,5 +158,12 @@ function renderEntry(entryFile, appRoot, routes) {
     const validationError = routes.some(route => route.validator)
         ? `import type { SimpleError } from '@vinejs/vine/types'\nexport type ValidationError = { errors: SimpleError[] }`
         : '';
-    return [...imports, validationError, `export interface Routes {\n${members.join('\n')}\n}`].join('\n');
+    const helpers = Object.entries(RESPONSE_HELPERS).map(([name, status]) => `    ${name}<T>(body?: T, etag?: boolean): { __response: T; __status: ${status} }`);
+    const augmentation = `declare module '@adonisjs/core/http' {\n  interface HttpResponse {\n${helpers.join('\n')}\n  }\n}`;
+    return [
+        ...imports,
+        validationError,
+        augmentation,
+        `export interface Routes {\n${members.join('\n')}\n}`,
+    ].join('\n');
 }

package/build/src/type_to_schema.d.ts

@@ -8,7 +8,11 @@ export declare class TypeToSchema {
     #private;
     readonly components: Record<string, JsonSchema>;
     readonly unsupported: Set<string>;
-    constructor(checker: ts.TypeChecker);
+    /**
+     * Every named type becomes a component up front: a transformer nested in another
+     * resolves to a different type than its `Data` alias, and is matched by its schema.
+     */
+    constructor(checker: ts.TypeChecker, named?: Map<ts.Type, string>);
     convert(type: ts.Type, stack?: ts.Type[]): JsonSchema;
     /**
      * Whether `undefined` is one of the members, which makes an object property optional.

package/build/src/type_to_schema.js

@@ -9,10 +9,24 @@ const BINARY = new Set(['MultipartFile', 'File', 'Blob']);
 export class TypeToSchema {
     #checker;
     #recursive = new Map();
+    #named;
+    #namesBySchema = new Map();
     components = {};
     unsupported = new Set();
-    constructor(checker) {
+    /**
+     * Every named type becomes a component up front: a transformer nested in another
+     * resolves to a different type than its `Data` alias, and is matched by its schema.
+     */
+    constructor(checker, named = new Map()) {
         this.#checker = checker;
+        this.#named = named;
+        for (const [type, name] of named) {
+            const schema = this.#properties(type, []);
+            const serialized = JSON.stringify(schema);
+            this.components[name] = schema;
+            if (!this.#namesBySchema.has(serialized))
+                this.#namesBySchema.set(serialized, name);
+        }
     }
     convert(type, stack = []) {
         const flags = type.flags;
@@ -93,8 +107,21 @@ export class TypeToSchema {
         return { anyOf: schemas };
     }
     #object(type, name, stack) {
+        const named = this.#named.get(type);
+        if (named)
+            return { $ref: `#/components/schemas/${named}` };
         if (stack.includes(type))
             return { $ref: `#/components/schemas/${this.#recursiveName(type, name)}` };
+        const schema = this.#properties(type, stack);
+        const ref = this.#recursive.get(type);
+        if (ref) {
+            this.components[ref] = schema;
+            return { $ref: `#/components/schemas/${ref}` };
+        }
+        const shared = this.#namesBySchema.get(JSON.stringify(schema));
+        return shared ? { $ref: `#/components/schemas/${shared}` } : schema;
+    }
+    #properties(type, stack) {
         const next = [...stack, type];
         const properties = {};
         const required = [];
@@ -115,11 +142,6 @@ export class TypeToSchema {
         };
         if (required.length)
             schema.required = required;
-        const ref = this.#recursive.get(type);
-        if (ref) {
-            this.components[ref] = schema;
-            return { $ref: `#/components/schemas/${ref}` };
-        }
         return schema;
     }
     #recursiveName(type, name) {

package/build/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { HttpContext } from '@adonisjs/core/http';
 export type JsonValue = string | number | boolean | null;
 /**
  * The JSON Schema keywords the generator reads or writes. Keywords Vine adds
@@ -39,12 +40,31 @@ export interface OpenApiConfig {
     info: {
         title: string;
         version: string;
+        summary?: string;
         description?: string;
+        termsOfService?: string;
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+            identifier?: string;
+        };
     };
     servers: {
         url: string;
         description?: string;
     }[];
+    /**
+     * Written as the document's top-level `tags`, to describe and order the tags operations use.
+     */
+    tags: {
+        name: string;
+        description?: string;
+    }[];
     /**
      * Same filters as Tuyau's `generateRegistry({ routes })`. Only one of them can be set.
      */
@@ -76,6 +96,10 @@ export interface RouteOperation {
         specifier: string;
         exportName: string;
     };
+    controller?: {
+        path: string;
+        method: string;
+    };
 }
 export interface OpenApiParameter {
     name: string;
@@ -91,7 +115,10 @@ export interface OpenApiResponse {
 }
 export interface OpenApiOperation {
     operationId: string;
+    summary?: string;
+    description?: string;
     tags: string[];
+    deprecated?: true;
     parameters?: OpenApiParameter[];
     requestBody?: {
         required: true;
@@ -106,9 +133,74 @@ export interface OpenApiDocument {
     openapi: '3.1.0';
     info: OpenApiConfig['info'];
     servers?: OpenApiConfig['servers'];
+    tags?: OpenApiConfig['tags'];
     paths: Record<string, Partial<Record<HttpMethod, OpenApiOperation>>>;
     components: {
         schemas: Record<string, JsonSchema>;
         securitySchemes: OpenApiConfig['securitySchemes'];
     };
 }
+/**
+ * What a docs UI needs to render its page.
+ */
+export interface DocsPage {
+    title: string;
+    /**
+     * Relative to the page, so the page keeps working behind a proxy that adds a path prefix.
+     */
+    documentUrl: string;
+    /**
+     * The CSP nonce Shield sets on the response, when CSP is enabled.
+     */
+    nonce?: string;
+}
+export type Json = JsonValue | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Serialized as JSON into the UI's own init call.
+ */
+export type UiOptions = {
+    [key: string]: Json;
+};
+export type DocsUi = {
+    ui?: 'scalar';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+    };
+} | {
+    ui: 'swagger-ui';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+        style?: string;
+    };
+} | {
+    ui: 'redoc';
+    uiOptions?: UiOptions;
+    cdn?: {
+        script?: string;
+    };
+} | {
+    ui: (page: DocsPage) => string;
+    uiOptions?: never;
+    cdn?: never;
+};
+export type DocsOptions = DocsUi & {
+    /**
+     * Path of the page. The document is served at `<prefix>/openapi.json`.
+     */
+    prefix?: string;
+    title?: string;
+    /**
+     * `live` generates the document on each request and needs the app's TypeScript
+     * sources. `file` serves the file `node ace openapi:generate` wrote.
+     */
+    source?: 'live' | 'file';
+    /**
+     * The file `source: 'file'` reads, relative to the app root. Defaults to the config `output`.
+     */
+    file?: string;
+    transform?: (document: OpenApiDocument, ctx: HttpContext) => OpenApiDocument | Promise<OpenApiDocument>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enzopita/adonisjs-openapi",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Generate an OpenAPI document from the routes, validators and transformers of an AdonisJS app",
   "keywords": [
     "adonisjs",
@@ -25,6 +25,8 @@
   "exports": {
     ".": "./build/index.js",
     "./commands": "./build/commands/main.js",
+    "./routes": "./build/src/docs/routes.js",
+    "./build_hook": "./build/src/build_hook.js",
     "./types": "./build/src/types.js"
   },
   "publishConfig": {