@enzopita/adonisjs-openapi 0.1.0 → 0.2.0

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,7 +57,195 @@ 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.
+
+## 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.
+
+### 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
 
@@ -60,6 +258,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' };
@@ -112,9 +119,11 @@ export async function generateDocument(app, router, config) {
             const scheme = config.middlewareSecurity[name];
             return 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 +153,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.0",
   "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": {