> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talosjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# swagger:create

> Generate a Swagger API explorer module from controller routes.

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

```bash theme={null}
talos swagger:create [options]
```

## Examples

Run with no flags to be prompted for the swagger name and design module:

```bash theme={null}
talos swagger:create
```

Generate documentation for the default `app` target:

```bash theme={null}
talos swagger:create --name=api-docs --design=ui
```

Document a microservice under a custom route prefix:

```bash theme={null}
talos swagger:create --name=billing-docs --module=billing --design=ui --prefix=gateway
```

Reinstall the explorer template while regenerating documentation:

```bash theme={null}
talos swagger:create --name=api-docs --force
```

## Options

| Option       | Description                                                                                                                            | Default                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `--name`     | Swagger module name. Normalized to kebab-case with any trailing `Module` stripped.                                                     | Prompted if omitted; `swagger` with `--silent` |
| `--module`   | Target module whose controllers are documented.                                                                                        | `app`                                          |
| `--design`   | Design module the explorer is styled from. Existing design modules can be selected interactively, or a new design name can be entered. | Prompted if omitted                            |
| `--prefix`   | Route prefix the backend mounts its controllers under. Leading and trailing slashes are trimmed.                                       | `api`                                          |
| `--cwd`      | Project directory the swagger is created in.                                                                                           | Current directory                              |
| `--silent`   | Suppress prompts, spinners, and output.                                                                                                | `false`                                        |
| `--force`    | Reinstall the explorer from the template instead of leaving an existing engine untouched.                                              | `false`                                        |
| `--no-cache` | Bypass the skeleton cache and re-download templates.                                                                                   | `false`                                        |

## 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.

<Tabs>
  <Tab title="Claude">
    ```bash theme={null}
    talos agent:skills:create
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    talos agent:skills:create
    ```
  </Tab>
</Tabs>