Skip to main content
Scaffold a browser API explorer and generate route documentation from controllers. The command writes modules/<name>/, modules/<name>/<name>.yml, modules/<name>/package.json, modules/<name>/vite.config.ts, modules/<name>/playwright.config.ts, generated route files under modules/<name>/src/features/, modules/<name>/public/openapi.json, and a root tsconfig.json path alias when that file exists.

​
Usage

​
Examples

Run with no flags to be prompted for the swagger name and design module:
Generate documentation for the default app target:
Document a microservice under a custom route prefix:
Reinstall the explorer template while regenerating documentation:

​
Options

​
Generated documentation

The command reads registered *Controller.ts files from the target modules. A target marked type: "api" documents backend modules marked type: "module" and type: "api"; any other target documents only its own controllers. Each documented route writes modules/<name>/src/features/<module>/<RouteName>.route.ts. The route metadata comes from the @Route.<verb> decorator and the route type’s params, queries, payload, and response blocks. Path parameters missing from the route type are added as required string params.

​
OpenAPI output

The command writes modules/<name>/public/openapi.json with OpenAPI 3.1.0. The server URL is /<prefix>, route paths use /v<version>, :param segments become {param}, non-socket routes become operations, and routes with roles receive bearer auth security.

​
Re-running

When modules/<name>/package.json already exists and --force is not set, the command only rewrites src/features/ and public/openapi.json. With --force, it copies the swagger template again, rewrites the package and Vite files, regenerates documentation, installs dependencies, ensures the design module exists, and adds the path alias.

​
AI Skill

This command ships a matching swagger:create skill. The skill runs talos swagger:create, then guides your AI agent through completing the generated route metadata, field docs, examples, error statuses, environments, and verification.