Create an OpenAPI document

Prepare a description of your HTTP API before using the AGENTO config generator. OpenAPI documents the paths, HTTP methods, inputs, authentication, and responses. The description must match your deployed backend.

AGENTO consumes this document. Your project chooses how to create it. It can be written by hand, exported from existing API tooling, or generated from annotations and shared schemas.

Choose a source of truth

Your project	Starting point
Already publishes OpenAPI	Export its JSON/YAML document and check its version and contents.
Has a small API without documentation	Write a local document using the downloadable example.
Has Express or Next.js routes	Add `@openapi` comments and export them with `swagger-jsdoc`.
Uses Zod for validation	Reuse input schemas through `@asteasolutions/zod-to-openapi`, and explicitly register paths and responses.

Route names alone do not describe required fields, validation rules, security, or response shapes. Comments/schema tooling still needs that information. If you use a model to help draft the document, verify its claims against route handlers, middleware, schemas, and actual API responses.

Document an Express operation

swagger-jsdoc reads OpenAPI annotations in source files. Install it as a development dependency:

npm install --save-dev swagger-jsdoc

In the route file, place a description above the handler you already have. This example assumes the public path is /api/services/:id:

/**
 * @openapi
 * /api/services/{id}:
 *   get:
 *     operationId: getService
 *     summary: Get a service
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           minLength: 1
 *     responses:
 *       '200':
 *         description: Service details
 */
app.get("/api/services/:id", getService);

app and getService are existing application values. This snippet documents a handler; it does not create its business implementation. Express uses :id in the route, while OpenAPI uses {id}. Include the public router prefix in the documented path; annotation export does not infer where a router is mounted.

Document a Next.js Route Handler

With App Router, an endpoint can live in src/app/api/services/[id]/route.ts. Add the same @openapi comment above your existing GET export, documenting /api/services/{id}.

For example, the handler below reads its dynamic route parameter. Keep your own data lookup and response implementation:

export async function GET(
  _request: Request,
  context: { params: Promise<{ id: string }> },
) {
  const { id } = await context.params;
  const service = await getService(id);
  return Response.json(service);
}

Here getService is your existing backend function. The file path and exported method define the route in Next.js. The OpenAPI comment separately describes its contract. The same comment scanner can read the source .ts file; it does not need to execute or import the handler.

For Pages Router, point the scanner at your pages/api or src/pages/api files and document each supported HTTP method explicitly. The downloadable export script below targets App Router; it does not automatically adapt Pages Router paths or method branching.

Export the annotations

Save export-openapi.mjs as scripts/export-openapi.mjs. Run it from the project root. The Express patterns assume route files live under src/routes; adjust them to your layout. Next.js patterns cover App Router with or without src.

import swaggerJsdoc from "swagger-jsdoc";
import { writeFileSync } from "node:fs";

const target = process.argv[2];
const sources = {
  express: ["./src/routes/**/*.{js,ts}"],
  next: ["./src/app/api/**/route.{js,ts}", "./app/api/**/route.{js,ts}"],
};
if (!Object.hasOwn(sources, target)) {
  throw new Error("Usage: node scripts/export-openapi.mjs <express|next>");
}

const document = swaggerJsdoc({
  failOnErrors: true,
  definition: {
    openapi: "3.0.3",
    info: { title: "Application API", version: "1.0.0" },
    servers: [{ url: "https://api.example.com" }],
  },
  apis: sources[target],
});
if (!Object.keys(document.paths ?? {}).length) {
  throw new Error("No documented operations found. Check source paths and @openapi comments.");
}
writeFileSync("openapi.json", JSON.stringify(document, null, 2) + "\n");

For Express:

node scripts/export-openapi.mjs express

For Next.js App Router:

node scripts/export-openapi.mjs next

The script deliberately rebuilds openapi.json from your annotations. Replace https://api.example.com with your actual server URL, or supply --base-url later when generating the AGENTO config. Match any server base path and public route prefix so they are not duplicated.

Inspect the exported paths, input schemas, and security definitions. failOnErrors detects annotation parsing/validation problems; it does not prove that every route is documented or that annotations match the live API. Comments must describe query/body constraints and security when those apply. Do not publish a protected operation as public because its annotation omitted authentication.

Swagger UI is optional. You can write openapi.json to disk and use it with AGENTO without hosting an interactive documentation page.

Reuse Zod schemas

If you already validate input with Zod, consider zod-to-openapi. It can reuse those schemas when you register operation paths, request inputs, and responses, then generate a complete document with generateDocument.

Zod schemas alone do not identify which HTTP route uses them. You still register method, path, operation ID, and security. Use a library version compatible with your Zod version, and export OpenAPI 3.0 or 3.1 for this AGENTO converter.

Generated OpenAPI can contain features outside AGENTO's conversion scope. For example, unions may produce oneOf/anyOf; schema defaults and arbitrary top-level body properties are also unsupported. Review supported inputs before conversion. Preserve the real API contract when adjusting your tooling.

Review and generate the AGENTO config

Before conversion, check these items:

The full public paths and HTTP methods match the backend.
Each operation has a unique compatible operationId.
Required fields, types, parameter locations, and constraints are documented.
Authentication matches the actual endpoint; secret values are absent.
The chosen server URL and base path point to the intended environment.
The operations fit the converter's supported scope.

Then use a release that includes the generator:

npx --no-install agento-openapi openapi.json --output config.generated.yml