DESCRIBE
YOUR API.

Initialize Project Structure with @domain-first/handlers-rest selected. Run the CLI and choose Add integration → OpenAPI. The menu item is available only when handlers-rest is in domainFirstPackages.

npx df-ps

Choose the HTTP route prefix served by your application, defaulting to /api, and the document destination. The document path is configurable; for example, public/openapi.json.

scripts/generate-openapi.ts
package.json → openapi script

Document after generation:
public/openapi.json  # configurable

The script imports restHandlers from your presentation/rest directory and calls generateOpenAPI. The document title comes from your package name. With wiring enabled, generating the first REST endpoint creates the handler collection.

Install the dependencies printed by the CLI. The script uses tsx and handlers-rest 7.0.2 or newer; missing or older dependencies trigger an installation suggestion.

npm run openapi

The script loads .env because imported wiring may read environment variables. Run it after adding or changing endpoints, then regenerate any API client that consumes the document.

Continue with Orval ↗ to generate typed React Query hooks from this document.

During OpenAPI setup, accept Fill operationId, summary and description from the endpoint logic TSDoc? to enable automatic metadata extraction. The optional extractor reads the handler class associated with each REST endpoint.

The scaffolder adds scripts/extract-open-api-data-from-endpoint.ts and connects it to the generation script. Install any extractor dependencies printed by the CLI. If a class has no TSDoc comment, its name can still provide operationId. Explicit endpoint openApiMetadata overrides extracted fields.

Add meaningful comments to the handler class, then rerun npm run openapi. Metadata extraction is optional: leave it disabled when you prefer to maintain operation metadata explicitly.