|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +sidebar_label: AsyncAPI 🆕 |
| 4 | +--- |
| 5 | + |
| 6 | +# AsyncAPI mode (`qraft asyncapi`) |
| 7 | + |
| 8 | +`qraft asyncapi` is the AsyncAPI-focused mode of the unified `@qraft/cli` package. |
| 9 | +It generates TypeScript schema types from AsyncAPI documents using AsyncAPI plugins. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +```bash npm2yarn |
| 14 | +npm install -D @qraft/cli @qraft/asyncapi-typescript-plugin |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +The command below generates AsyncAPI TypeScript schema types into the `src/events` directory: |
| 20 | + |
| 21 | +```bash npm2yarn |
| 22 | +npx qraft asyncapi --plugin asyncapi-typescript ./asyncapi.yaml --output-dir src/events |
| 23 | +``` |
| 24 | + |
| 25 | +## Generated output example |
| 26 | + |
| 27 | +Below is a real excerpt of generated code (from plugin snapshots): |
| 28 | + |
| 29 | +```ts |
| 30 | +/** |
| 31 | + * This file was auto-generated by @qraft/cli. |
| 32 | + * Do not make direct changes to the file. |
| 33 | + */ |
| 34 | + |
| 35 | +export interface servers { |
| 36 | + "events-test": components["servers"]["events-test"]; |
| 37 | + /** @description Production WebSocket server for events (lighting measurements) secured with TLS */ |
| 38 | + "events-prod": { |
| 39 | + host: "prod-events.example.com"; |
| 40 | + protocol: "wss"; |
| 41 | + }; |
| 42 | +} |
| 43 | + |
| 44 | +export interface channels { |
| 45 | + lightingMeasured: { |
| 46 | + address: "/events/streetlights/{streetlightId}/lighting/measured"; |
| 47 | + messages: { |
| 48 | + lightMeasured: components["messages"]["lightMeasured"]; |
| 49 | + lightMeasuredResponse: components["messages"]["lightMeasuredResponse"]; |
| 50 | + }; |
| 51 | + parameters: { |
| 52 | + streetlightId: "streetlight-1" | "streetlight-2"; |
| 53 | + }; |
| 54 | + servers: [ |
| 55 | + servers["events-test"], |
| 56 | + servers["events-prod"] |
| 57 | + ]; |
| 58 | + }; |
| 59 | +} |
| 60 | + |
| 61 | +export interface operations { |
| 62 | + receiveLightMeasurement: { |
| 63 | + action: "receive"; |
| 64 | + channel: channels["lightingMeasured"]; |
| 65 | + messages: [ |
| 66 | + channels["lightingMeasured"]["messages"]["lightMeasured"] |
| 67 | + ]; |
| 68 | + reply: { |
| 69 | + channel: channels["lightingMeasured"]; |
| 70 | + messages: [ |
| 71 | + channels["lightingMeasured"]["messages"]["lightMeasuredResponse"] |
| 72 | + ]; |
| 73 | + }; |
| 74 | + summary: "Server receives light measurement data from a sensor and responds with acknowledgment."; |
| 75 | + }; |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +## Options |
| 80 | + |
| 81 | +### Required |
| 82 | + |
| 83 | +- **`-o <path>, --output-dir <path>`**: Specify where to output generated files. |
| 84 | + - Example: `--output-dir src/events` |
| 85 | + |
| 86 | +### Optional |
| 87 | + |
| 88 | +- **`-c, --clean`**: Clean the output directory before generation. |
| 89 | +- **`--file-header <string>`**: Add a custom header to each generated file, useful for disabling linting rules or adding file comments. |
| 90 | + - Example: `--file-header '/* eslint-disable */'` |
| 91 | +- **`--redocly [config]`**: Use the Redocly configuration to generate multiple API clients. If the `[config]` parameter is not specified, the default Redocly configuration will be used: `[redocly.yaml | redocly.yml | .redocly.yaml | .redocly.yml]`. |
| 92 | + - Examples: |
| 93 | + - `--redocly` |
| 94 | + - `--redocly ./my-redocly-config.yaml` |
| 95 | + - `qraft asyncapi events --redocly` |
| 96 | + - For more information about this option, use the command: `--redocly-help` or [read the docs](../cli/redocly-config.mdx). |
| 97 | +- **`--plugin <name_1> --plugin <name_2>`**: Generator plugins to be used. (choices: `asyncapi-typescript`) |
| 98 | + - Example: `--plugin asyncapi-typescript` |
| 99 | +- **`-h, --help`**: Display help for the command. |
| 100 | + |
| 101 | +## Plugin System |
| 102 | + |
| 103 | +The following plugin is currently supported: |
| 104 | + |
| 105 | +- `asyncapi-typescript` - Generates TypeScript types from an AsyncAPI Document. |
| 106 | + |
| 107 | +:::tip |
| 108 | +Plugin must be provided with the `--plugin <name>` option. |
| 109 | +::: |
| 110 | + |
| 111 | +### `--plugin asyncapi-typescript` options |
| 112 | + |
| 113 | +- **`--asyncapi-types-file-name <path>`**: AsyncAPI Schema types file name, e.g., `schema.d.ts` (default: `schema.ts`). |
| 114 | + - Must end with `.ts` or `.d.ts`. |
| 115 | + - Must not include path separators (`/` or `\`). |
| 116 | + - Must not start with `.`. |
| 117 | +- **`--enum`**: Export true TypeScript enums instead of unions. |
| 118 | +- **`--enum-values`**: Export enum values as arrays. |
| 119 | +- **`--dedupe-enums`**: Dedupe enum types when `--enum` is set. |
| 120 | +- **`-t, --export-type`**: Export top-level `type` instead of `interface`. |
| 121 | +- **`--immutable`**: Generate readonly types. |
| 122 | +- **`--additional-properties`**: Treat schema objects as if `additionalProperties: true` is set. |
| 123 | +- **`--empty-objects-unknown`**: Generate `unknown` instead of `Record<string, never>` for empty objects. |
| 124 | +- **`--default-non-nullable`**: Set to `false` to ignore default values when generating non-nullable types. |
| 125 | +- **`--properties-required-by-default`**: Treat schema objects as if `required` is set to all properties by default. |
| 126 | +- **`--alphabetize`**: Sort object keys alphabetically. |
| 127 | +- **`--exclude-deprecated`**: Exclude deprecated fields from types. |
| 128 | + |
| 129 | +## Redocly config support |
| 130 | + |
| 131 | +AsyncAPI generation can be configured in `redocly.yaml` via `x-asyncapi-qraft`: |
| 132 | + |
| 133 | +```yaml |
| 134 | +apis: |
| 135 | + events: |
| 136 | + root: ./asyncapi.yaml |
| 137 | + x-asyncapi-qraft: |
| 138 | + plugin: |
| 139 | + asyncapi-typescript: true |
| 140 | + output-dir: src/events |
| 141 | + clean: true |
| 142 | + asyncapi-types-file-name: asyncapi.ts |
| 143 | +``` |
| 144 | +
|
| 145 | +Then run: |
| 146 | +
|
| 147 | +```bash npm2yarn |
| 148 | +npx qraft asyncapi --redocly |
| 149 | +# or generate both OpenAPI + AsyncAPI entries |
| 150 | +npx qraft redocly |
| 151 | +``` |
0 commit comments