Skip to content

docs: add api generation for components #1767

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
batchu5 wants to merge 8 commits into
base: master
Choose a base branch
from
Open

docs: add api generation for components #1767

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3ff3f65
docs: add api generation for components
batchu5 Nov 23, 2025
810948d
Replaced ModelinaGenerator class with typedef
batchu5 Nov 23, 2025
431b8d1
Add Sequential execution in generate:assets command
batchu5 Nov 23, 2025
c521c81
Add glob Pattern to ./src/**/* in docs to ensure consistent behaviour…
batchu5 Nov 23, 2025
20dc33b
Fix grammar in source JSDoc descriptions
batchu5 Nov 23, 2025
3fcc3d4
Add API.md in files section of package.json
batchu5 Nov 23, 2025
a5b9b38
changed from src -> lib
batchu5 Nov 23, 2025
34f53ff
fix: replace '?' with | undefined for optional params
batchu5 Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 199 additions & 0 deletions packages/components/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
## Functions
### **CloseConnection** - Renders a WebSocket close connection method with optional pre- and post-execution logic.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | Programming language used for method formatting. |
| props.framework | string | Framework used, if any (e.g., 'quarkus' for Java). |
| props.methodName | string | Name of the method to generate. |
| props.methodParams | Array.<string> | List of parameters for the method. |
| props.preExecutionCode | string | Code to insert before the main function logic. |
| props.postExecutionCode | string | Code to insert after the main function logic. |
| props.indent | number | Indentation level for the method block. |

### Returns
- **JSX.Element** - Rendered method block with appropriate formatting.
### **Connect** - Component that renders WebSocket connection method for the specified programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component properties. |
| props.language | SupportedLanguage | The programming language for which to generate connection code. |
| props.title | string | The title of the WebSocket server. |

### **resolveDependencies** - Helper function to resolve dependencies based on language, framework, and role.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| language | Language | The programming language. |
| framework | string | The framework (e.g., 'quarkus' for Java). |
| role | string | The role (e.g., 'client', 'connector' for Java). |

### Returns
- **Array.<string>** - Array of dependency strings.
### **DependencyProvider** - Renders the top-of-file dependency statements for the selected programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | The programming language for which to render dependency statements. |
| props.framework | string | The framework (e.g., 'quarkus' for Java). |
| props.role | string | The role (e.g., 'client', 'connector' for Java). |
| props.additionalDependencies | Array.<string> | Optional additional dependencies to include. |

### Returns
- **JSX.Element** - Rendered list of import/require statements.
### **FileHeaderInfo** - Renders a file header with metadata information such as title, version, protocol, host, and path.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.info | object | Info object from the AsyncAPI document. |
| props.server | object | Server object from the AsyncAPI document. |
| props.language | Language | Programming language used for comment formatting. |

### Returns
- **JSX.Element** - Rendered file header.
### **ownKeys** - Configuration for WebSocket message handler method logic per language.

### **HandleMessage** - Renders a WebSocket message handler method with optional pre- and post-execution logic.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | Programming language used for method formatting. |
| props.methodName | string | Name of the method to generate. |
| props.methodParams | Array.<string> | List of parameters for the method. |
| props.preExecutionCode | string | Code to insert before the main function logic. |
| props.postExecutionCode | string | Code to insert after the main function logic. |
| props.customMethodConfig | Object | Optional overrides for default method configuration. |

### Returns
- **JSX.Element** - Rendered method block with appropriate formatting.
### **resolveDocsAndLogic** - Resolve docs and logic for the given language + framework config.

### **buildIndentedLogic** - Build indented method body.

### **MethodGenerator** - Generic Method rendering component.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | Programming language used for method formatting. |
| props.methodName | string | Name of the method. |
| props.methodParams | Array.<string> | Method parameters. |
| props.methodDocs | string | Optional documentation string. |
| props.methodLogic | string | Core method logic. |
| props.preExecutionCode | string | Code before main logic. |
| props.postExecutionCode | string | Code after main logic. |
| props.indent | number | Indentation for the method block. |
| props.newLines | number | Number of new lines after method. |
| props.customMethodConfig | Object | Optional custom syntax configuration for the current language. |
| props.methodConfig | Record.<Language, ({methodDocs: string, methodLogic: string}|Record.<string, {methodDocs: string, methodLogic: string}>)> | Language-level or framework-level configuration. |
| props.framework | string | Framework name for nested configurations (e.g., 'quarkus' for Java). |

### **Models** - Generates and returns an array of model files based on the AsyncAPI document.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| params | Object | The parameters for the function. |
| params.asyncapi | AsyncAPIDocumentInterface | Parsed AsyncAPI document object. |
| params.language | Language | Target programming language for the generated models. |
| params.format | Format | Naming format for generated files. |
| params.presets | object | Custom presets for the generator instance. |
| params.constraints | object | Custom constraints for the generator instance. |

### Returns
- **Array.<File>** - Array of File components with generated model content.
### **OnClose** - Component that renders WebSocket onClose event handler for the specified programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component properties. |
| props.language | SupportedLanguage | The programming language for which to generate onClose handler code. |
| props.framework | string | Optional framework variant (e.g., 'quarkus' for java). |
| props.title | string | The title of the WebSocket server. |

### **OnError** - Component that renders WebSocket onError event handler for the specified programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component properties. |
| props.language | SupportedLanguage | The programming language for which to generate onError handler code. |

### **OnMessage** - Component that renders WebSocket onMessage event handler for the specified programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component properties. |
| props.language | SupportedLanguage | The programming language for which to generate onMessage handler code. |

### **OnOpen** - Component that renders WebSocket onOpen event handler for the specified programming language.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component properties. |
| props.language | SupportedLanguage | The programming language for which to generate onOpen handler code. |
| props.framework | string | Optional framework variant (e.g., 'quarkus' for java). |
| props.title | string | The title of the WebSocket server. |

### **resolveQueryParamLogic** - Resolve the appropriate query parameter configuration function based on language and framework.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| language | SupportedLanguage | The target programming language. |
| framework | string | Optional framework (e.g., 'quarkus' for Java). |

### Returns
- **function** - The configuration function for generating query parameter code.
### **QueryParamsVariables** - Component for rendering query parameter variables code.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | SupportedLanguage | The target programming language. |
| props.framework | string | Optional framework for the language. |
| props.queryParams | Array.<Array.<string>> | Array of query parameters, each represented as [paramName, paramType?]. |

### **ownKeys** - Configuration for WebSocket error handler registration method logic per language.

### **RegisterErrorHandler** - Renders a WebSocket error handler registration method with optional pre- and post-execution logic.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | Programming language used for method formatting. |
| props.methodName | string | Name of the method to generate. |
| props.methodParams | Array.<string> | List of parameters for the method. |
| props.preExecutionCode | string | Code to insert before the main function logic. |
| props.postExecutionCode | string | Code to insert after the main function logic. |
| props.customMethodConfig | Object | Optional overrides for default method configuration. |

### Returns
- **JSX.Element** - Rendered method block with appropriate formatting.
### **ownKeys** - Configuration for WebSocket message handler registration method logic per language.

### **RegisterMessageHandler** - Renders a WebSocket message handler registration method with optional pre- and post-execution logic.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | Language | Programming language used for method formatting. |
| props.methodName | string | Name of the method to generate. |
| props.methodParams | Array.<string> | List of parameters for the method. |
| props.preExecutionCode | string | Code to insert before the main function logic. |
| props.postExecutionCode | string | Code to insert after the main function logic. |

### Returns
- **JSX.Element** - Rendered method block with appropriate formatting.
### **SendOperations** - Component for rendering WebSocket send operation methods.
Generates both static and instance methods for sending messages through WebSocket connections.
### Parameters
| Name | Type | Description |
|------|------|-------------|
| props | Object | Component props. |
| props.language | SupportedLanguage | The target programming language. |
| props.sendOperations | Array.<Object> | Array of send operations from AsyncAPI document. |
| props.clientName | string | The name of the client class. |

19 changes: 19 additions & 0 deletions packages/components/api.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
## Functions
{{#functions}}
### **{{name}}** - {{description}}
{{#if params.length}}
### Parameters
| Name | Type | Description |
|------|------|-------------|
{{#each params}}
| {{name}} | {{type.names.[0]}} | {{description}} |
Copy link

@coderabbitai coderabbitai bot Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Use Handlebars-standard array index syntax.

The bracket notation .[0] is non-standard for Handlebars. Use .0 instead to access the first array element.

Apply this diff:

-| {{name}} | {{type.names.[0]}} | {{description}} |
+| {{name}} | {{type.names.0}} | {{description}} |
📝 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.

Suggested change
| {{name}} | {{type.names.[0]}} | {{description}} |
| {{name}} | {{type.names.0}} | {{description}} |
🤖 Prompt for AI Agents 
In packages/components/api.hbs around line 9, the template uses non-standard
Handlebars bracket notation `.[0]` to access the first array element; replace
`{{type.names.[0]}}` with the Handlebars-standard `{{type.names.0}}` so the
template uses proper array index syntax and renders correctly.

{{/each}}
{{/if}}

{{#if returns.length}}
### Returns
{{#each returns}}
- **{{type.names.[0]}}**{{#if description}} - {{description}}{{/if}}
{{/each}}
{{/if}}
{{/functions}}
139 changes: 71 additions & 68 deletions packages/components/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,71 @@
{
"name": "@asyncapi/generator-components",
"version": "0.3.1",
"description": "Package with reusable components for generation using React render engine",
"scripts": {
"test": "npm run build && jest --coverage",
"test:update": "npm run test -- -u",
"build": "babel src --out-dir lib",
"prepublishOnly": "npm run build",
"lint": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore .",
"lint:fix": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore . --fix",
"generate:assets": "npm run prepublishOnly"
},
"files": [
"lib/**",
"README.md",
"LICENSE"
],
"main": "lib/index.js",
"repository": {
"type": "git",
"url": "https://github.com/asyncapi/generator.git",
"directory": "packages/components"
},
"author": "Lukasz Gornicki",
"license": "Apache-2.0",
"publishConfig": {
"access": "public"
},
"dependencies": {
"@asyncapi/generator-react-sdk": "*",
"@asyncapi/generator-helpers": "*",
"@asyncapi/modelina": "^5.3.5"
},
"devDependencies": {
"@babel/cli": "^7.25.9",
"@babel/core": "^7.26.0",
"@babel/preset-env": "^7.26.0",
"@babel/preset-react": "^7.25.9",
"jest": "^27.3.1",
"jest-esm-transformer": "^1.0.0"
},
"jest": {
"moduleFileExtensions": [
"js",
"json",
"jsx"
],
"transform": {
"^.+\\.jsx?$": "babel-jest"
},
"moduleNameMapper": {
"^nimma/legacy$": "<rootDir>/../../node_modules/nimma/dist/legacy/cjs/index.js",
"^nimma/(.*)": "<rootDir>/../../node_modules/nimma/dist/cjs/$1"
}
},
"babel": {
"presets": [
"@babel/preset-env",
[
"@babel/preset-react",
{
"runtime": "automatic"
}
]
]
}
}
{
"name": "@asyncapi/generator-components",
"version": "0.3.1",
"description": "Package with reusable components for generation using React render engine",
"scripts": {
"test": "npm run build && jest --coverage",
"test:update": "npm run test -- -u",
"build": "babel src --out-dir lib",
"prepublishOnly": "npm run build",
"lint": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore .",
"lint:fix": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore . --fix",
"generate:assets": "npm run prepublishOnly && npm run docs",
"docs": "jsdoc2md --template api.hbs \"./lib/**/*.js\" > API.md"
},
"files": [
"lib/**",
"README.md",
"API.md",
"LICENSE"
],
"main": "lib/index.js",
"repository": {
"type": "git",
"url": "https://github.com/asyncapi/generator.git",
"directory": "packages/components"
},
"author": "Lukasz Gornicki",
"license": "Apache-2.0",
"publishConfig": {
"access": "public"
},
"dependencies": {
"@asyncapi/generator-react-sdk": "*",
"@asyncapi/generator-helpers": "*",
"@asyncapi/modelina": "^5.3.5"
},
"devDependencies": {
"@babel/cli": "^7.25.9",
"@babel/core": "^7.26.0",
"@babel/preset-env": "^7.26.0",
"@babel/preset-react": "^7.25.9",
"jest": "^27.3.1",
"jest-esm-transformer": "^1.0.0",
"jsdoc-to-markdown": "^9.1.3"
Copy link

@coderabbitai coderabbitai bot Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify jsdoc-to-markdown v9.1.3 is actively maintained and free from vulnerabilities.

The version pinning strategy (caret ^9.1.3) allows patch and minor updates. Ensure this version resolves the JSDoc type parsing issue mentioned in the PR (optional-property marker ? in Record types) and is free from security advisories.

🌐 Web query:

Does jsdoc-to-markdown v9.1.3 support optional property markers in JSDoc Record types, and are there known security advisories for this version?

💡 Result:

Short answer:

  • No — jsdoc-to-markdown (v9.1.3) does not add special support for "question‑mark" optional property markers inside JSDoc record type syntax; JSDoc/Closure-style record types generally require either the square-bracket property form ([@Property {T} [name]]) or an explicit union with undefined (e.g. T|undefined). (jsdoc.app)

  • No known public security advisories specific to jsdoc-to-markdown v9.1.3 were reported in major vulnerability trackers (Snyk / npm metadata) at the time of checking. (security.snyk.io)

If you want, I can show an example JSDoc workaround (square-bracket/@Property or |undefined) and a quick scan of your project for indirect dependency advisories.

Citations:

Dependency version does not support the stated JSDoc optional-property marker feature.

Web verification confirms that jsdoc-to-markdown v9.1.3 does not support optional property markers (?) in JSDoc Record types—the standard workarounds require square-bracket syntax or explicit undefined unions instead. If the PR intends to resolve the optional-property marker parsing issue via this dependency upgrade, v9.1.3 will not achieve that. No security advisories were found for this version.

🤖 Prompt for AI Agents 
In packages/components/package.json at line 43, the dependency
jsdoc-to-markdown@^9.1.3 does not support JSDoc Record optional-property marker
(`?`), so the upgrade will not fix parsing of `?` in Record types; either update
the dependency to a version that explicitly adds support for `?` (verify release
notes/changelog before bumping) or revert this change and instead update the
source JSDoc to use supported alternatives (square-bracket optional syntax or
explicit `| undefined` unions) and add a comment in the package.json/change log
explaining why the dependency was not upgraded.

Copy link
Author

@batchu5 batchu5 Nov 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so should i replace the '?' mark with sqaure brackets

},
"jest": {
"moduleFileExtensions": [
"js",
"json",
"jsx"
],
"transform": {
"^.+\\.jsx?$": "babel-jest"
},
"moduleNameMapper": {
"^nimma/legacy$": "<rootDir>/../../node_modules/nimma/dist/legacy/cjs/index.js",
"^nimma/(.*)": "<rootDir>/../../node_modules/nimma/dist/cjs/$1"
}
},
"babel": {
"presets": [
"@babel/preset-env",
[
"@babel/preset-react",
{
"runtime": "automatic"
}
]
]
}
}
4 changes: 2 additions & 2 deletions packages/components/src/components/CloseConnection.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ const delayExit = 1000;

/**
* Configuration for WebSocket close method logic per language.
* @type {Record<Language, { methodDocs?: string, methodLogic: string }>}
* @type {Record<Language, { methodDocs: string | undefined, methodLogic: string }>}
*/
const websocketCloseConfig = {
python: {
Expand Down Expand Up @@ -58,7 +58,7 @@ print('WebSocket connection closed.');`
};

/**
* Renders a WebSocket close connection method with optional pre and post execution logic.
* Renders a WebSocket close connection method with optional pre- and post-execution logic.
*
* @param {Object} props - Component props.
* @param {Language} props.language - Programming language used for method formatting.
Expand Down
4 changes: 2 additions & 2 deletions packages/components/src/components/HandleMessage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { MethodGenerator } from './MethodGenerator';

/**
* Configuration for WebSocket message handler method logic per language.
* @type {Record<Language, { methodDocs?: string, methodLogic: string }>}
* @type {Record<Language, { methodDocs: string | undefined, methodLogic: string }>}
*/
const websocketHandleMessageConfig = {
python: {
Expand All @@ -28,7 +28,7 @@ else:
};

/**
* Renders a WebSocket message handler method with optional pre and post execution logic.
* Renders a WebSocket message handler method with optional pre- and post-execution logic.
*
* @param {Object} props - Component props.
* @param {Language} props.language - Programming language used for method formatting.
Expand Down
Loading