docs(generator): update latest generator documentation #4359
Conversation
asyncapi-bot
requested review from
TRohit20,
asyncapi-bot-eve and
thulieblack
as code owners
✅ Deploy Preview for asyncapi-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughDocumentation updates introduce “baked-in templates” concept, expand configuration references, and add API docs for a new public Generator class and a global listBakedInTemplates function. Changes are confined to markdown under docs/tools/generator, including a new baked-in templates page and reorganized templates overview. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
Status, Documentation and Community
|
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-4359--asyncapi-website.netlify.app/ |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4359 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (10)
markdown/docs/tools/generator/api.md (1)
523-528: Minor grammar and clarity pass on filter optionsHyphenate and clarify examples; no behavior change.
Apply this diff:
-- [filter] `Object` - Optional filter object. - - [.type] `string` - Filter by template type (e.g., 'client', 'docs'). - - [.stack] `string` - Filter by stack (e.g., 'quarkus', 'express'). - - [.protocol] `string` - Filter by protocol (e.g., 'websocket', 'http'). - - [.target] `string` - Filter by target language or format (e.g., 'javascript', 'html'). +- [filter] `Object` - Optional filter object. + - [.type] `string` - Filter by template type (for example, `client`, `docs`). + - [.stack] `string` - Filter by stack/framework (for example, `quarkus`, `express`). + - [.protocol] `string` - Filter by protocol (for example, `websocket`, `http`, `kafka`). + - [.target] `string` - Filter by target language or format (for example, `javascript`, `html`, `yaml`).markdown/docs/tools/generator/baked-in-templates.md (6)
8-11: Concise wordingReplace “a variety of” and streamline the sentence.
Apply this diff:
-Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the `generator` repository and exposed with `@asyncapi/generator` library**. - -AsyncAPI Generator supports a variety of baked-in template types for generating code, documentation, configs, and SDKs. All templates are managed under the `packages/templates` directory and follow a strict, opinionated directory structure for consistency and ease of maintenance. +Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the Generator repository and exposed by the `@asyncapi/generator` library**. + +AsyncAPI Generator supports several baked-in template types for generating code, documentation, configuration, and SDKs. All templates are managed under the `packages/templates` directory and follow an opinionated directory structure for consistency and maintainability.
12-12: Avoid bare URL; make it a proper linkThis satisfies MD034 and improves UX.
Apply this diff:
-> List of baked-in templates: https://github.com/asyncapi/generator/blob/master/apps/generator/lib/templates/BakedInTemplatesList.json +> List of baked-in templates: [BakedInTemplatesList.json](https://github.com/asyncapi/generator/blob/master/apps/generator/lib/templates/BakedInTemplatesList.json)
23-25: Clarify note and fix agreement“are always plural” → “must be plural.” Keep consistent exceptions.
Apply this diff:
-> **Note:** -> The **directory name is always plural** (e.g., `clients`), but the **type recorded in metadata and package name is singular** (e.g., `client`), except for `docs`. +> **Note:** +> The **directory name must be plural** (for example, `clients`), but the **type recorded in metadata and the package name is singular** (for example, `client`), except for `docs`.
31-33: Add a language hint to fenced code blockSatisfies MD040.
Apply this diff:
-``` +```text packages/templates/{type}/[protocol]/[target]/[stack]--- `55-59`: **Normalize terminology and hyphenation** Use “normalizes,” “baked-in,” and article usage. Apply this diff: ```diff -Generator build runs a script that normalize metadata for baked-in templates and their naming: -- Adds/updates metadata in `.ageneratorrc` file. You do not have to maintain it manually. -- Validates/updates template name in `package.json` file of given template. The name always starts with `core-template-` prefix. -- Generates JSON file with list of baked in templates and stores the list inside the generator: `apps/generator/lib/templates/BakedInTemplatesList.json` +The Generator build runs a script that normalizes metadata and naming for baked-in templates: +- Adds/updates metadata in the `.ageneratorrc` file (no manual maintenance required). +- Validates/updates the template name in the template’s `package.json`. The name always starts with the `core-template-` prefix. +- Generates a JSON file with the list of baked-in templates and stores it in the Generator: `apps/generator/lib/templates/BakedInTemplatesList.json`.
86-100: Tighten language and verify “react-sdk” namingMinor grammar fixes; also please confirm whether the correct package name is “react-sdk” or another (for example,
@asyncapi/react-component). If different, update here.Apply this diff:
-Templates that are exposed as part of the generator are transpiled with the `react-sdk` and located in published library under `/lib/templates/bakedInTemplates`. This means that in case of baked-in templates, they are not picked by the generator from `node_modules`. This way the process of generation is faster and more efficient. +Templates exposed by the Generator are transpiled with the `react-sdk` and located in the published library under `/lib/templates/bakedInTemplates`. For baked-in templates, the Generator does not load them from `node_modules`. This makes generation faster and more efficient.markdown/docs/tools/generator/template.md (1)
26-29: List indentation and wording nitsBring the list to standard indentation and tighten phrasing.
Apply this diff:
-Baked-in templates benefit from: -- **Tight integration** with the generator’s features and release cycle. -- **Instant availability:** They are bundled as part of every release, so you never need to install or fetch them separately. -- **Unified contributions:** Any improvements or changes to these templates happen through pull requests to the generator repository itself, keeping everything in sync. They share a lot of common parts which makes templates development faster. +Baked-in templates benefit from: +- **Tight integration** with the Generator’s features and release cycle. +- **Instant availability:** They are bundled with every release, so you never need to install or fetch them separately. +- **Unified contributions:** Improvements happen via pull requests to the Generator repository, keeping everything in sync.markdown/docs/tools/generator/configuration-file.md (2)
153-155: Style nit: use “incompatible” for concisionOptional wording improvement.
Apply this diff:
-| `apiVersion` | String | Determines which **major** version of the [Parser-API](https://github.com/asyncapi/parser-api) the template uses. For example, `v2` for `v2.x.x`. If not specified, the Generator assumes the template is not compatible with the Parser-API so it will use the [Parser-JS v1 API](https://github.com/asyncapi/parser-js/tree/v1.18.1#api-documentation). For templates that need to support AsyncAPI specification v3 make sure to use `v3` [Parser-API](https://github.com/asyncapi/parser-api). If the template uses a version of the Parser-API that is not supported by the Generator, the Generator will throw an error. | +| `apiVersion` | String | Determines which **major** version of the [Parser-API](https://github.com/asyncapi/parser-api) the template uses. For example, `v2` for `v2.x.x`. If not specified, the Generator assumes the template is incompatible with the Parser-API and will use the [Parser-JS v1 API](https://github.com/asyncapi/parser-js/tree/v1.18.1#api-documentation). For templates that need to support AsyncAPI specification v3, use `v3` of the Parser-API. If the template uses a Parser-API version unsupported by the Generator, it will throw an error. |
165-166: Tighten wording inparameterandvalidationrowsMake examples crisper; no behavior change.
Apply this diff:
-| `conditionalGeneration[filePath/directoryName].parameter` | String | The `parameter` is the name of a custom template parameter passed through `templateParams` that controls whether a specific file or folder should be included in the generated output. You must define a `validation` rule using a JSON Schema fragment to apply the condition. For example, if you define `"parameter": "includeDocs"` with `"validation": { "const": true }`, the corresponding folder (e.g., `docs/`) will only be generated when the user passes `{ includeDocs: true }`. If `includeDocs` is `false`, it will be skipped. | -| `conditionalGeneration[filePath/directoryName].validation` | Object (JSON Schema fragment) | The validation defines the condition under which the file or directory will be generated. It must be a valid JSON Schema fragment that validates the value of the parameter. For example, if you want to include a folder only when includeDocs is true, use "validation": `{ "const": true }`. You can also use more complex validation logic, like "enum": ["yes", "true"] or "type": "string" with a "pattern" constraint. If the parameter fails validation, the file or folder will not be included in the generated output. This allows for powerful and flexible control over template generation based on user input. | +| `conditionalGeneration[filePath/directoryName].parameter` | String | The name of a custom template parameter (passed via `templateParams`) that controls whether a specific file or folder is generated. Pair it with a JSON Schema `validation` rule. Example: `"parameter": "includeDocs"` with `"validation": { "const": true }` generates `docs/` only when `{ includeDocs: true }`. | +| `conditionalGeneration[filePath/directoryName].validation` | Object (JSON Schema fragment) | A JSON Schema fragment defining when the file or directory is generated. Example: `{ "const": true }` or `{ "enum": ["yes", "true"] }`, or a string `pattern`. If validation fails, the path is skipped. |
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
markdown/docs/tools/generator/api.md(2 hunks)markdown/docs/tools/generator/baked-in-templates.md(1 hunks)markdown/docs/tools/generator/configuration-file.md(4 hunks)markdown/docs/tools/generator/template.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tools/generator/api.md
[grammar] ~516-~516: There might be a mistake here.
Context: ...er by type, stack, protocol, or target. Use name of returned templates as input for...
(QB_NEW_EN)
[grammar] ~517-~517: There might be a mistake here.
Context: ...e, stack, protocol, or target. Use name of returned templates as input for the `ge...
(QB_NEW_EN)
markdown/docs/tools/generator/configuration-file.md
[style] ~154-~154: Consider using “incompatible” to avoid wordiness.
Context: ..., the Generator assumes the template is not compatible with the Parser-API so it will use the ...
(NOT_ABLE_PREMIUM)
[style] ~158-~158: To form a complete sentence, be sure to include a subject.
Context: ...alue of the parameter if not specified. Shouldn't be used for mandatory `required=true...
(MISSING_IT_THERE)
[grammar] ~167-~167: There might be a mistake here.
Context: ...ul when you want to copy binary files. | | generator | [String] | A string repr...
(QB_NEW_EN)
[grammar] ~169-~169: There might be a mistake here.
Context: ...s that can be used as Nunjucks filters. In case of external modules, remember they...
(QB_NEW_EN)
[style] ~178-~178: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...server from the specification file they want to use during generation. You also need th...
(REP_WANT_TO_VB)
[style] ~178-~178: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...on. You also need this parameter if you want to use server.protocol notation within `...
(REP_WANT_TO_VB)
[grammar] ~178-~178: Ensure spelling is correct
Context: ...if your users do not use this parameter obligatory.
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
markdown/docs/tools/generator/baked-in-templates.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...plates is limited and solution is still in experimental phase. It is not recommend...
(QB_NEW_EN)
[style] ~10-~10: Consider using a more concise synonym.
Context: ...library**. AsyncAPI Generator supports a variety of baked-in template types for generating ...
(A_VARIETY_OF)
[grammar] ~18-~18: There might be a mistake here.
Context: ...): Templates that generate documentation - client: Templates that generate clients - `sdk...
(QB_NEW_EN)
[grammar] ~23-~23: There might be a mistake here.
Context: ... generate configuration files > Note: > The directory name is always plural ...
(QB_NEW_EN)
[grammar] ~36-~36: There might be a mistake here.
Context: ...orts, e.g. websocket, http, kafka. - target: The output language, markup, or format...
(QB_NEW_EN)
[grammar] ~37-~37: There might be a mistake here.
Context: ... javascript, python, html, yaml. - stack: (Optional, for clients and sdks) U...
(QB_NEW_EN)
[grammar] ~44-~44: There might be a mistake here.
Context: ... or configs/yaml). - clients/sdks: Path must be type/protocol/target or `...
(QB_NEW_EN)
[grammar] ~49-~49: There might be a mistake here.
Context: ...ery template directory must include: - .ageneratorrc: Generator specific configuration, like...
(QB_NEW_EN)
[grammar] ~51-~51: There might be a mistake here.
Context: ...example parameters - package.json: It contains template name. Version information shou...
(QB_NEW_EN)
[grammar] ~57-~57: There might be a mistake here.
Context: ...ays starts with core-template- prefix. - Generates JSON file with list of baked i...
(QB_NEW_EN)
[grammar] ~58-~58: There might be a mistake here.
Context: ...emplate-` prefix. - Generates JSON file with list of baked in templates and stores t...
(QB_NEW_EN)
[grammar] ~62-~62: There might be a mistake here.
Context: ...# Example Example information provided for template stored under `packages/templat...
(QB_NEW_EN)
[grammar] ~100-~100: There might be a mistake here.
Context: ...spiled with the react-sdk and located in published library under `/lib/templates...
(QB_NEW_EN)
markdown/docs/tools/generator/template.md
[grammar] ~21-~21: There might be a mistake here.
Context: ...plates is limited and solution is still in experimental phase Baked-in templates ...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ... generator’s features and release cycle. - Instant availability: They are bundled...
(QB_NEW_EN)
[style] ~28-~28: Consider using a synonym to be more concise.
Context: ... keeping everything in sync. They share a lot of common parts which makes templates deve...
(A_LOT_OF)
🪛 markdownlint-cli2 (0.17.2)
markdown/docs/tools/generator/baked-in-templates.md
12-12: Bare URL used
(MD034, no-bare-urls)
31-31: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
60-60: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
markdown/docs/tools/generator/template.md
29-29: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
30-30: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
31-31: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
32-32: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
33-33: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
34-34: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
35-35: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
36-36: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Automerge PR autoapproved by a bot
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Test NodeJS PR - windows-latest
- GitHub Check: Test NodeJS PR - ubuntu-latest
- GitHub Check: Test NodeJS PR - macos-13
- GitHub Check: Lighthouse CI
🔇 Additional comments (4)
markdown/docs/tools/generator/template.md (1)
34-36: Standalone templates heading and intro look goodThe separation between baked-in and standalone templates is clear and helpful.
markdown/docs/tools/generator/configuration-file.md (3)
8-10: Good clarity around metadata scopeClear distinction between baked-in vs standalone usage of
metadata.
18-23: YAML example looks correct and aligns with the baked-in metadata specNo issues found.
77-88: JSON example aligns with YAML and fields; LGTMConsistent with the baked-in metadata requirements.
| <dt><a href="#listBakedInTemplates">listBakedInTemplates</a> ⇒ <code>Array.<Object></code></dt> | ||
| <dd><p>List core templates, optionally filter by type, stack, protocol, or target. | ||
| Use name of returned templates as input for the <code>generate</code> method for template generation. Such core templates code is part of the @asyncapi/generator package.</p></dd> | ||
| </dl> |
There was a problem hiding this comment.
Use consistent terminology (“baked-in templates”) and fix grammar in Members description
Switch “core templates” to “baked-in templates” for consistency with the new docs and tighten the phrasing.
Apply this diff:
-<dd><p>List core templates, optionally filter by type, stack, protocol, or target.
-Use name of returned templates as input for the <code>generate</code> method for template generation. Such core templates code is part of the @asyncapi/generator package.</p></dd>
+<dd><p>List baked-in templates, optionally filtered by type, stack, protocol, or target.
+Use the returned template <em>name</em> as the <code>templateName</code> when calling the <code>Generator</code>. Baked-in template code ships with the <code>@asyncapi/generator</code> package.</p></dd>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <dt><a href="#listBakedInTemplates">listBakedInTemplates</a> ⇒ <code>Array.<Object></code></dt> | |
| <dd><p>List core templates, optionally filter by type, stack, protocol, or target. | |
| Use name of returned templates as input for the <code>generate</code> method for template generation. Such core templates code is part of the @asyncapi/generator package.</p></dd> | |
| </dl> | |
| <dt><a href="#listBakedInTemplates">listBakedInTemplates</a> ⇒ <code>Array.<Object></code></dt> | |
| <dd><p>List baked-in templates, optionally filtered by type, stack, protocol, or target. | |
| Use the returned template <em>name</em> as the <code>templateName</code> when calling the <code>Generator</code>. Baked-in template code ships with the <code>@asyncapi/generator</code> package.</p></dd> | |
| </dl> |
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/api.md around lines 17 to 20, the Members
description uses inconsistent terminology ("core templates") and has awkward
phrasing; update the text to use "baked-in templates" consistently and tighten
grammar — e.g., replace occurrences of "core templates" with "baked-in
templates", reword the sentence to: "List baked-in templates; optionally filter
by type, stack, protocol, or target. Use the returned template names as input to
the generate method. Baked-in templates are included in the @asyncapi/generator
package." Ensure markup and code tags remain unchanged.
| <a name="listBakedInTemplates"></a> | ||
|
|
||
| ## listBakedInTemplates | ||
| List core templates, optionally filter by type, stack, protocol, or target. | ||
| Use name of returned templates as input for the `generate` method for template generation. Such core templates code is part of the @asyncapi/generator package. | ||
|
|
||
| **Kind**: global variable | ||
| **Returns**: `Array.<Object>` - Array of template objects matching the filter. | ||
| **Params** |
There was a problem hiding this comment.
“Kind” is wrong; document full function signature and return shape
This section currently labels the API as a “global variable.” It is a callable function. Also, adding the parameter list to the heading and clarifying the return objects improves usability.
Apply this diff:
-## listBakedInTemplates
-List core templates, optionally filter by type, stack, protocol, or target.
-Use name of returned templates as input for the `generate` method for template generation. Such core templates code is part of the @asyncapi/generator package.
-
-**Kind**: global variable
-**Returns**: `Array.<Object>` - Array of template objects matching the filter.
+## listBakedInTemplates([filter]) ⇒ `Array.<Object>`
+List baked-in templates, optionally filtered by type, stack, protocol, or target.
+Use the returned template name as the `templateName` when calling the `Generator`. Baked-in templates are bundled with `@asyncapi/generator`.
+
+**Kind**: global function
+**Returns**: `Array.<{ name: string, type: string, protocol?: string, target: string, stack?: string }>` - Template descriptors matching the filter. 📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <a name="listBakedInTemplates"></a> | |
| ## listBakedInTemplates | |
| List core templates, optionally filter by type, stack, protocol, or target. | |
| Use name of returned templates as input for the `generate` method for template generation. Such core templates code is part of the @asyncapi/generator package. | |
| **Kind**: global variable | |
| **Returns**: `Array.<Object>` - Array of template objects matching the filter. | |
| **Params** | |
| <a name="listBakedInTemplates"></a> | |
| ## listBakedInTemplates([filter]) ⇒ `Array.<Object>` | |
| List baked-in templates, optionally filtered by type, stack, protocol, or target. | |
| Use the returned template name as the `templateName` when calling the `Generator`. Baked-in templates are bundled with `@asyncapi/generator`. | |
| **Kind**: global function | |
| **Returns**: `Array.<{ name: string, type: string, protocol?: string, target: string, stack?: string }>` - Template descriptors matching the filter. | |
| **Params** |
🧰 Tools
🪛 LanguageTool
[grammar] ~516-~516: There might be a mistake here.
Context: ...er by type, stack, protocol, or target. Use name of returned templates as input for...
(QB_NEW_EN)
[grammar] ~517-~517: There might be a mistake here.
Context: ...e, stack, protocol, or target. Use name of returned templates as input for the `ge...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/api.md around lines 513 to 521, the entry for
listBakedInTemplates incorrectly labels the API as a "global variable" and lacks
the full function signature, parameter list in the heading, and a clear return
shape; update the section to declare it as a function (include its full
signature with optional filter parameter and types), move or add the parameter
list into the heading or immediately under it, and expand the Returns
description to specify the exact array element shape (fields and types) rather
than a generic Object so consumers know what properties each template contains.
| weight: 55 | ||
| --- | ||
|
|
||
| > This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase. It is not recommended to use them in production. Instead join us to help to improve them with your use cases and your AsyncAPI documents. |
There was a problem hiding this comment.
Tighten the experimental note and fix grammar
Improve readability; add articles and punctuation.
Apply this diff:
-> This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase. It is not recommended to use them in production. Instead join us to help to improve them with your use cases and your AsyncAPI documents.
+> This is a new concept introduced in Generator version 2.8. The number of templates is limited, and the solution is still in the experimental phase. We do not recommend using them in production yet. Instead, please join us and help improve them with your use cases and AsyncAPI documents.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase. It is not recommended to use them in production. Instead join us to help to improve them with your use cases and your AsyncAPI documents. | |
| > This is a new concept introduced in Generator version 2.8. The number of templates is limited, and the solution is still in the experimental phase. We do not recommend using them in production yet. Instead, please join us and help improve them with your use cases and AsyncAPI documents. |
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: There might be a mistake here.
Context: ...plates is limited and solution is still in experimental phase. It is not recommend...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/baked-in-templates.md around line 6, the
experimental note is grammatically awkward and missing articles/punctuation;
rewrite the sentence to be concise and correct (add definite/indefinite
articles, commas and periods) and tighten the cautionary tone—e.g., state that
baked-in templates were introduced in generator v2.8, are limited and
experimental, and recommend against production use while inviting contributors
to help improve them; update the line accordingly for clarity and proper
grammar.
| - `docs` (not yet implemented): Templates that generate documentation | ||
| - `client`: Templates that generate clients | ||
| - `sdk` (not yet implemented): Template that generate full sdk's | ||
| - `config` (not yet implemented): Template that generate configuration files | ||
|
|
There was a problem hiding this comment.
Pluralization and capitalization fixes in supported types
Fix verb agreement and SDK capitalization.
Apply this diff:
-- `docs` (not yet implemented): Templates that generate documentation
-- `client`: Templates that generate clients
-- `sdk` (not yet implemented): Template that generate full sdk's
-- `config` (not yet implemented): Template that generate configuration files
+- `docs` (not yet implemented): Templates that generate documentation.
+- `client`: Templates that generate clients.
+- `sdk` (not yet implemented): Templates that generate full SDKs.
+- `config` (not yet implemented): Templates that generate configuration files.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `docs` (not yet implemented): Templates that generate documentation | |
| - `client`: Templates that generate clients | |
| - `sdk` (not yet implemented): Template that generate full sdk's | |
| - `config` (not yet implemented): Template that generate configuration files | |
| - `docs` (not yet implemented): Templates that generate documentation. | |
| - `client`: Templates that generate clients. | |
| - `sdk` (not yet implemented): Templates that generate full SDKs. | |
| - `config` (not yet implemented): Templates that generate configuration files. |
🧰 Tools
🪛 LanguageTool
[grammar] ~18-~18: There might be a mistake here.
Context: ...): Templates that generate documentation - client: Templates that generate clients - `sdk...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/baked-in-templates.md around lines 18 to 22,
fix pluralization and SDK capitalization: change "Template that generate full
sdk's" to "Templates that generate full SDKs" (remove the apostrophe and
capitalize SDK), and ensure the other entries use plural "Templates"
consistently (e.g., "Template that generate configuration files" -> "Templates
that generate configuration files" and "Template that generate full SDKs" fixed
likewise).
| Every template directory **must include**: | ||
| - `.ageneratorrc`: Generator specific configuration, like for example parameters | ||
| - `package.json`: It contains template name. Version information should not be provided as it is versioned together with the generator. | ||
|
|
There was a problem hiding this comment.
Grammar fixes in “Required files”
Hyphenate compound adjectives and clarify sentences.
Apply this diff:
-Every template directory **must include**:
-- `.ageneratorrc`: Generator specific configuration, like for example parameters
-- `package.json`: It contains template name. Version information should not be provided as it is versioned together with the generator.
+Every template directory **must include**:
+- `.ageneratorrc`: Generator-specific configuration (for example, parameters).
+- `package.json`: Contains the template name. Do not include a version; templates are versioned together with the Generator.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Every template directory **must include**: | |
| - `.ageneratorrc`: Generator specific configuration, like for example parameters | |
| - `package.json`: It contains template name. Version information should not be provided as it is versioned together with the generator. | |
| Every template directory **must include**: | |
| - `.ageneratorrc`: Generator-specific configuration (for example, parameters). | |
| - `package.json`: Contains the template name. Do not include a version; templates are versioned together with the Generator. |
🧰 Tools
🪛 LanguageTool
[grammar] ~49-~49: There might be a mistake here.
Context: ...ery template directory must include: - .ageneratorrc: Generator specific configuration, like...
(QB_NEW_EN)
[grammar] ~51-~51: There might be a mistake here.
Context: ...example parameters - package.json: It contains template name. Version information shou...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/baked-in-templates.md around lines 49 to 52,
the "Required files" bullets need grammar and clarity fixes: hyphenate compound
adjectives (change "Generator specific configuration" to "Generator-specific
configuration"), make the package.json sentence clearer and firmer (reword "It
contains template name. Version information should not be provided as it is
versioned together with the generator." to a single clear sentence such as
"package.json contains the template name; do not include version information
because the template is versioned together with the generator."), and ensure
punctuation and capitalization are consistent across the bullet list.
| - Validates/updates template name in `package.json` file of given template. The name always starts with `core-template-` prefix. | ||
| - Generates JSON file with list of baked in templates and stores the list inside the generator: `apps/generator/lib/templates/BakedInTemplatesList.json` | ||
|
|
||
| #### Example |
There was a problem hiding this comment.
Fix heading level increment (MD001)
Change H4 to H3 to avoid skipping a level.
Apply this diff:
-#### Example
+### Example📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #### Example | |
| ### Example |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
60-60: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/baked-in-templates.md around line 60, the
heading "#### Example" skips a level; change it from H4 to H3 by replacing "####
Example" with "### Example" so heading levels increment correctly (and scan
nearby headings to ensure no other level skips).
| The `generator` property from `package.json` file must contain a JSON object and the `ageneratorrc` file must contain a YAML object that may have the following information: | ||
|
|
There was a problem hiding this comment.
Fix file name and article usage
Add leading dot to .ageneratorrc and definite articles.
Apply this diff:
-The `generator` property from `package.json` file must contain a JSON object and the `ageneratorrc` file must contain a YAML object that may have the following information:
+The `generator` property in the `package.json` file must contain a JSON object, and the `.ageneratorrc` file must contain a YAML object with the following information:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The `generator` property from `package.json` file must contain a JSON object and the `ageneratorrc` file must contain a YAML object that may have the following information: | |
| The `generator` property in the `package.json` file must contain a JSON object, and the `.ageneratorrc` file must contain a YAML object with the following information: |
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/configuration-file.md around lines 144-145, the
text refers to "ageneratorrc" without the leading dot and omits definite
articles; update the filename to ".ageneratorrc" and adjust phrasing to use
definite articles (e.g., "the package.json file" and "the .ageneratorrc file")
so the sentence reads clearly and correctly.
| |`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name. | ||
|
|
||
| --- | ||
| | `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must be an object with the keys `subject`, `parameter` and `validation`. You can use either subject or parameter according to the use case. The path should be relative to the `template` directory inside the template. **Note: conditionalGeneration and conditionalFile are mutually exclusive, which means both cannot be configured at the same time in the template**. | |
There was a problem hiding this comment.
Fix option name: “conditionalFiles” (plural) and mutual exclusivity note
Currently says “conditionalFile.” Also minor clarity improvement.
Apply this diff:
-| `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must be an object with the keys `subject`, `parameter` and `validation`. You can use either subject or parameter according to the use case. The path should be relative to the `template` directory inside the template. **Note: conditionalGeneration and conditionalFile are mutually exclusive, which means both cannot be configured at the same time in the template**. |
+| `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must include either `subject` or `parameter`, plus `validation`. The path should be relative to the `template` directory. **Note: `conditionalGeneration` and `conditionalFiles` are mutually exclusive; do not configure both in the same template.** |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must be an object with the keys `subject`, `parameter` and `validation`. You can use either subject or parameter according to the use case. The path should be relative to the `template` directory inside the template. **Note: conditionalGeneration and conditionalFile are mutually exclusive, which means both cannot be configured at the same time in the template**. | | |
| | `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must include either `subject` or `parameter`, plus `validation`. The path should be relative to the `template` directory. **Note: `conditionalGeneration` and `conditionalFiles` are mutually exclusive; do not configure both in the same template.** | |
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/configuration-file.md around line 163, update
the option name and mutual-exclusivity note: replace any occurrence of
“conditionalFile” with “conditionalFiles” (plural) and rephrase the sentence to
read clearly that conditionalGeneration and conditionalFiles are mutually
exclusive (they cannot both be configured in the same template). Also make a
small clarity tweak to the surrounding text to state that each key is a file
path or directory relative to the template directory and each value must be an
object with optional subject or parameter and a required validation object.
| | Name | Description | | ||
| |------|-------------| | ||
| | `server` | It is used to let the template know which server from the AsyncAPI specification file you want to use. In some cases, this may be required. For instance, when generating code that connects to a specific server. Use this parameter in case your template relies on users' information about what server from the specification file they want to use during generation. You also need this parameter if you want to use `server.protocol` notation within `conditionalGeneration` configuration option. Once you decide to specify this parameter for your template, it is recommended you make it a mandatory parameter otherwise a feature like `conditionalGeneration` is not going to work if your users do not use this parameter obligatory. No newline at end of file |
There was a problem hiding this comment.
Special parameter “server”: shorten and fix “obligatory”
“Obligatory” → “required,” streamline for clarity.
Apply this diff:
-| `server` | It is used to let the template know which server from the AsyncAPI specification file you want to use. In some cases, this may be required. For instance, when generating code that connects to a specific server. Use this parameter in case your template relies on users' information about what server from the specification file they want to use during generation. You also need this parameter if you want to use `server.protocol` notation within `conditionalGeneration` configuration option. Once you decide to specify this parameter for your template, it is recommended you make it a mandatory parameter otherwise a feature like `conditionalGeneration` is not going to work if your users do not use this parameter obligatory.
+| `server` | Indicates which server from the AsyncAPI document to use (for example, when generating code that connects to a specific server). Required if your template relies on `server` data or uses `server.protocol` inside `conditionalGeneration`. If you support this parameter, make it required; otherwise, `conditionalGeneration` rules that reference `server` cannot work reliably. |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Name | Description | | |
| |------|-------------| | |
| | `server` | It is used to let the template know which server from the AsyncAPI specification file you want to use. In some cases, this may be required. For instance, when generating code that connects to a specific server. Use this parameter in case your template relies on users' information about what server from the specification file they want to use during generation. You also need this parameter if you want to use `server.protocol` notation within `conditionalGeneration` configuration option. Once you decide to specify this parameter for your template, it is recommended you make it a mandatory parameter otherwise a feature like `conditionalGeneration` is not going to work if your users do not use this parameter obligatory. | |
| | Name | Description | | |
| |------|-------------| | |
| | `server` | Indicates which server from the AsyncAPI document to use (for example, when generating code that connects to a specific server). Required if your template relies on `server` data or uses `server.protocol` inside `conditionalGeneration`. If you support this parameter, make it required; otherwise, `conditionalGeneration` rules that reference `server` cannot work reliably. | |
🧰 Tools
🪛 LanguageTool
[style] ~178-~178: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...server from the specification file they want to use during generation. You also need th...
(REP_WANT_TO_VB)
[style] ~178-~178: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...on. You also need this parameter if you want to use server.protocol notation within `...
(REP_WANT_TO_VB)
[grammar] ~178-~178: Ensure spelling is correct
Context: ...if your users do not use this parameter obligatory.
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/configuration-file.md around lines 176 to 178,
the description for the `server` parameter is verbose and uses "obligatory"
incorrectly; shorten and clarify by replacing "obligatory" with "required" and
streamlining the wording: make the text concise about when to use `server`, that
it's needed for templates relying on a specific AsyncAPI server or when using
`server.protocol` in conditionalGeneration, and recommend making it a required
parameter if conditionalGeneration depends on it.
| Templates can be developed as standalone project. There is also a set of baked-in core templates that are available in the generator out of the box. | ||
|
|
||
| ### Baked-in templates | ||
|
|
||
| > This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase | ||
|
|
||
| Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the `generator` repository and exposed with `@asyncapi/generator` library**. Source code of these templates live in the `packages/templates` directory of the `generator` repository. These templates and are managed alongside the generator’s core source code. Baked-in templates are always available “out of the box” when using the generator. No separate installation or network fetching is required. | ||
|
|
||
| Baked-in templates benefit from: | ||
| - **Tight integration** with the generator’s features and release cycle. | ||
| - **Instant availability:** They are bundled as part of every release, so you never need to install or fetch them separately. | ||
| - **Unified contributions:** Any improvements or changes to these templates happen through pull requests to the generator repository itself, keeping everything in sync. They share a lot of common parts which makes templates development faster. | ||
|
|
||
| In contrast, **standalone templates** (described below) are maintained as independent Node.js packages, may live in separate repositories, and can be managed or installed separately from the core generator. | ||
|
|
||
| Learn more from document [Baked-in Templates](#baked-in-templates). | ||
|
|
There was a problem hiding this comment.
Baked-in section: fix punctuation, agreement, and a duplicated word; improve link
- Add period to the experimental note.
- Fix “These templates and are…” duplicate.
- Capitalize SDKs.
- Replace in-page anchor with a cross-page link to the dedicated doc.
Apply this diff:
-### Baked-in templates
-
-> This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase
-
-Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the `generator` repository and exposed with `@asyncapi/generator` library**. Source code of these templates live in the `packages/templates` directory of the `generator` repository. These templates and are managed alongside the generator’s core source code. Baked-in templates are always available “out of the box” when using the generator. No separate installation or network fetching is required.
+### Baked-in templates
+
+> This is a new concept introduced in Generator version 2.8. The number of templates is limited, and the solution is still in the experimental phase.
+
+Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the Generator repository and exposed by the `@asyncapi/generator` library**. The source code lives in the `packages/templates` directory of the Generator repository. These templates are managed alongside the Generator’s core source code and are always available “out of the box.” No separate installation or network fetching is required.
@@
-- **Unified contributions:** Any improvements or changes to these templates happen through pull requests to the generator repository itself, keeping everything in sync. They share a lot of common parts which makes templates development faster.
+- **Unified contributions:** Improvements to these templates happen through pull requests to the Generator repository, keeping everything in sync. They share many common parts, which makes template development faster.
@@
-Learn more from document [Baked-in Templates](#baked-in-templates).
+See [Baked-in templates](baked-in-templates) for details.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Templates can be developed as standalone project. There is also a set of baked-in core templates that are available in the generator out of the box. | |
| ### Baked-in templates | |
| > This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase | |
| Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the `generator` repository and exposed with `@asyncapi/generator` library**. Source code of these templates live in the `packages/templates` directory of the `generator` repository. These templates and are managed alongside the generator’s core source code. Baked-in templates are always available “out of the box” when using the generator. No separate installation or network fetching is required. | |
| Baked-in templates benefit from: | |
| - **Tight integration** with the generator’s features and release cycle. | |
| - **Instant availability:** They are bundled as part of every release, so you never need to install or fetch them separately. | |
| - **Unified contributions:** Any improvements or changes to these templates happen through pull requests to the generator repository itself, keeping everything in sync. They share a lot of common parts which makes templates development faster. | |
| In contrast, **standalone templates** (described below) are maintained as independent Node.js packages, may live in separate repositories, and can be managed or installed separately from the core generator. | |
| Learn more from document [Baked-in Templates](#baked-in-templates). | |
| ### Baked-in templates | |
| > This is a new concept introduced in Generator version 2.8. The number of templates is limited, and the solution is still in the experimental phase. | |
| Baked-in templates are official AsyncAPI templates that are **developed, versioned, and shipped directly inside the Generator repository and exposed by the `@asyncapi/generator` library**. The source code lives in the `packages/templates` directory of the Generator repository. These templates are managed alongside the Generator’s core source code and are always available “out of the box.” No separate installation or network fetching is required. | |
| Baked-in templates benefit from: | |
| - **Tight integration** with the generator’s features and release cycle. | |
| - **Instant availability:** They are bundled as part of every release, so you never need to install or fetch them separately. | |
| - **Unified contributions:** Improvements to these templates happen through pull requests to the Generator repository, keeping everything in sync. They share many common parts, which makes template development faster. | |
| In contrast, **standalone templates** (described below) are maintained as independent Node.js packages, may live in separate repositories, and can be managed or installed separately from the core generator. | |
| See [Baked-in templates](baked-in-templates) for details. |
🧰 Tools
🪛 LanguageTool
[grammar] ~21-~21: There might be a mistake here.
Context: ...plates is limited and solution is still in experimental phase Baked-in templates ...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ... generator’s features and release cycle. - Instant availability: They are bundled...
(QB_NEW_EN)
[style] ~28-~28: Consider using a synonym to be more concise.
Context: ... keeping everything in sync. They share a lot of common parts which makes templates deve...
(A_LOT_OF)
🪛 markdownlint-cli2 (0.17.2)
29-29: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
30-30: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
31-31: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
32-32: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
33-33: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
🤖 Prompt for AI Agents
In markdown/docs/tools/generator/template.md around lines 17 to 33, fix
punctuation and phrasing: add a period at the end of the experimental note
sentence, remove the duplicated word so “These templates and are…” becomes
“These templates are…”, capitalize “SDKs” where applicable, and replace the
in-page anchor link "[Baked-in Templates](#baked-in-templates)" with a
cross-page link pointing to the dedicated baked-in templates doc (use the
correct relative path to that doc). Ensure the modified sentences remain
grammatically correct and preserve the original meaning.
Updated generator documentation is available and this PR introduces update to generator folder on the website
Summary by CodeRabbit