@enzopita/adonisjs-openapi 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enzo Pita <enzo@enzopita.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# @enzopita/adonisjs-openapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate an OpenAPI 3.1 document from an AdonisJS 7 app, with no annotations. The generator reads the same sources as [Tuyau](https://github.com/Julien-R44/tuyau):
+
+| OpenAPI                             | Source                                                                                         |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 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                                                  |
+| `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
+
+```sh
+node ace add @enzopita/adonisjs-openapi
+```
+
+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
+
+```sh
+node ace openapi:generate
+```
+
+The command boots the app the way `node ace codegen` does, so no database connection or queue worker starts. It writes `openapi.json` at the app root. To write it somewhere else, pass `--output=public/openapi.json` or set `output` in the config.
+
+## Configure
+
+```ts
+// config/openapi.ts
+import { defineConfig } from '@enzopita/adonisjs-openapi'
+
+export default defineConfig({
+  output: 'openapi.json',
+  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' },
+  },
+  middlewareSecurity: {
+    auth: 'accessToken',
+  },
+})
+```
+
+- `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.
+- `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
+
+- A route must have a name and a controller handler. Closure routes are skipped, as they are in Tuyau.
+- 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.
+- `Date` and Luxon `DateTime` values become `{ type: 'string', format: 'date-time' }`.
+- A handler that returns a model or an untyped object produces a `200` response with no schema and a warning. Return `serialize(...)` to type it.
+
+## Limitations
+
+- 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/commands/generate_openapi.d.ts

@@ -0,0 +1,8 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class GenerateOpenApi extends BaseCommand {
+    #private;
+    static commandName: string;
+    static description: string;
+    output?: string;
+    run(): Promise<void>;
+}

package/build/commands/generate_openapi.js

@@ -0,0 +1,49 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { dirname, join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { defineConfig } from "../src/define_config.js";
+export default class GenerateOpenApi extends BaseCommand {
+    static commandName = 'openapi:generate';
+    static description = 'Generate an OpenAPI document from the routes, validators and transformers';
+    /**
+     * Same warm-up as `node ace codegen`: the app is assembled like the web
+     * environment, but never becomes ready, so no long-running side effect starts.
+     */
+    async #warmUpApp() {
+        this.app.setEnvironment('web');
+        this.app.setMode('warmup');
+        await this.app.boot();
+        await this.app.warmUp();
+        const router = await this.app.container.make('router');
+        router.commit();
+        return router;
+    }
+    async run() {
+        const router = await this.#warmUpApp();
+        const config = this.app.config.get('openapi') ?? defineConfig();
+        const startTime = process.hrtime();
+        // Loaded on run: it pulls in the TypeScript compiler, which every other ace command would pay for.
+        const { generateDocument } = await import("../src/generate.js");
+        const { document, warnings } = await generateDocument(this.app, router, config);
+        for (const warning of warnings)
+            this.logger.warning(warning);
+        const output = join(fileURLToPath(this.app.appRoot), this.output ?? config.output);
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, `${JSON.stringify(document, null, 2)}\n`);
+        this.logger.success(`OpenAPI document written to ${this.app.relativePath(output)}`, {
+            startTime,
+        });
+    }
+}
+__decorate([
+    flags.string({
+        description: 'Output file, relative to the app root. Defaults to config/openapi.ts "output"',
+    })
+], GenerateOpenApi.prototype, "output", void 0);

package/build/commands/main.d.ts

@@ -0,0 +1,4 @@
+import type { CommandMetaData } from '@adonisjs/core/types/ace';
+import GenerateOpenApi from './generate_openapi.ts';
+export declare function getMetaData(): Promise<CommandMetaData[]>;
+export declare function getCommand(metaData: CommandMetaData): Promise<typeof GenerateOpenApi | null>;

package/build/commands/main.js

@@ -0,0 +1,7 @@
+import GenerateOpenApi from "./generate_openapi.js";
+export async function getMetaData() {
+    return [{ ...GenerateOpenApi.serialize(), filePath: 'generate_openapi.js' }];
+}
+export async function getCommand(metaData) {
+    return metaData.commandName === GenerateOpenApi.commandName ? GenerateOpenApi : null;
+}

package/build/configure.d.ts

@@ -0,0 +1,2 @@
+import type Configure from '@adonisjs/core/commands/configure';
+export declare function configure(command: Configure): Promise<void>;

package/build/configure.js

@@ -0,0 +1,16 @@
+import { stubsRoot } from "./stubs/main.js";
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    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

@@ -0,0 +1,9 @@
+import type { generateDocument as generate } from './src/generate.ts';
+export { configure } from './configure.ts';
+export { defineConfig } from './src/define_config.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

@@ -0,0 +1,11 @@
+export { configure } from "./configure.js";
+export { defineConfig } from "./src/define_config.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.d.ts

@@ -0,0 +1,7 @@
+import type { Router } from '@adonisjs/core/http';
+import type { OpenApiConfig, RouteOperation } from './types.ts';
+/**
+ * Scans the committed router with the same routes scanner the dev server feeds
+ * Tuyau, so both see the same request and response types.
+ */
+export declare function collectRoutes(appRoot: string, router: Router, config: OpenApiConfig): Promise<RouteOperation[]>;

package/build/src/collect_routes.js

@@ -0,0 +1,66 @@
+import { RoutesScanner } from '@adonisjs/assembler/routes_scanner';
+const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options']);
+function matches(routeName, matcher) {
+    if (matcher instanceof RegExp)
+        return matcher.test(routeName);
+    if (matcher instanceof Function)
+        return matcher(routeName);
+    return routeName.includes(matcher);
+}
+function isIncluded(routeName, filters) {
+    if (filters.only)
+        return filters.only.some(matcher => matches(routeName, matcher));
+    if (filters.except)
+        return !filters.except.some(matcher => matches(routeName, matcher));
+    return true;
+}
+/**
+ * `/users/:id/:slug?` becomes `/users/{id}/{slug}`, the only form OpenAPI paths accept.
+ */
+function toOpenApiPath(pattern) {
+    return pattern.replace(/:([^/?]+)\??/g, '{$1}').replace(/\*/g, '{wildcard}');
+}
+/**
+ * Scans the committed router with the same routes scanner the dev server feeds
+ * Tuyau, so both see the same request and response types.
+ */
+export async function collectRoutes(appRoot, router, config) {
+    const live = router.toJSON();
+    const middlewareByRoute = new Map();
+    for (const route of Object.values(live).flat()) {
+        const names = [...route.middleware.all()].flatMap(entry => 'name' in entry && entry.name ? [entry.name] : []);
+        middlewareByRoute.set(`${route.domain}:${route.pattern}:${route.methods.join(',')}`, names);
+    }
+    // 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 serialized)
+        await scanner.scan(routes);
+    return scanner.getScannedRoutes().map(route => {
+        const pattern = toOpenApiPath(route.pattern);
+        const [validator] = route.validators ?? [];
+        return {
+            name: route.name,
+            methods: route.methods
+                .map(method => method.toLowerCase())
+                .filter((method) => METHODS.has(method)),
+            path: pattern,
+            pathParams: [...pattern.matchAll(/\{([^}]+)\}/g)].map(match => match[1]),
+            middleware: middlewareByRoute.get(`${route.domain}:${route.pattern}:${route.methods.join(',')}`) ?? [],
+            requestType: route.request?.type,
+            responseType: route.response?.type,
+            imports: [...(route.request?.imports ?? []), ...(route.response?.imports ?? [])],
+            validator: validator && {
+                specifier: validator.import.specifier,
+                exportName: validator.import.value,
+            },
+            controller: route.controller && {
+                path: route.controller.path,
+                method: route.controller.method,
+            },
+        };
+    });
+}

package/build/src/define_config.d.ts

@@ -0,0 +1,2 @@
+import type { OpenApiConfig } from './types.ts';
+export declare function defineConfig(config?: Partial<OpenApiConfig>): OpenApiConfig;

package/build/src/define_config.js

@@ -0,0 +1,15 @@
+export function defineConfig(config = {}) {
+    if (config.routes?.only && config.routes.except) {
+        throw new Error('openapi: use either "routes.only" or "routes.except", not both');
+    }
+    return {
+        output: 'openapi.json',
+        info: { title: 'API', version: '1.0.0' },
+        servers: [],
+        tags: [],
+        routes: {},
+        securitySchemes: {},
+        middlewareSecurity: {},
+        ...config,
+    };
+}

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;