feat: add support for AsyncAPI 2 and 3 in the split command#2552
feat: add support for AsyncAPI 2 and 3 in the split command#2552tibisabau wants to merge 4 commits intoRedocly:mainfrom
Conversation
🦋 Changeset detectedLatest commit: d2699f3 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
| splitDefinition(openapi, outDir, separator, ext); | ||
| const definition = readYaml(api) as AnyDefinition; | ||
|
|
||
| const specType = validateDefinitionFileName(api, definition); |
There was a problem hiding this comment.
It seems like returning specType from validateDefinitionFileName breaks single responsibility principle.
Could you please do detect spec separately from validation.
| collectSpecData?.(definition); | ||
|
|
||
| if (specType === 'openapi') { | ||
| splitDefinition(definition as AnyOas3Definition, outDir, separator, ext); |
There was a problem hiding this comment.
Lets rename it to splitOASDefinition.
| const openapi = readYaml(api) as AnyOas3Definition; | ||
| collectSpecData?.(openapi); | ||
| splitDefinition(openapi, outDir, separator, ext); | ||
| const definition = readYaml(api) as AnyDefinition; |
There was a problem hiding this comment.
It looks like we also checked that file exist before readYaml before the change inside
validateDefinitionFileName.
| } | ||
|
|
||
| function validateDefinitionFileName(fileName: string) { | ||
| function validateDefinitionFileName(fileName: string, file?: Definition): 'openapi' | 'asyncapi' { |
There was a problem hiding this comment.
It’s not immediately clear why the validate function returns the equivalent of detectSpec.
| fs.mkdirSync(asyncapiDir, { recursive: true }); | ||
|
|
||
| const componentsFiles: ComponentsFiles = {}; | ||
| const detectedVersion = detectSpec(asyncapi); |
There was a problem hiding this comment.
It looks like you already called detectSpec previously in the flow, could you please check if it make sense to pass the result as parameter?
| iterateAsyncApiComponents(asyncapi, asyncapiDir, componentsFiles, ext, specVersion); | ||
|
|
||
| // Split channels | ||
| if ((asyncapi as any).channels) { |
There was a problem hiding this comment.
Why this type cast is necessary?
Both v2 and v3 AsyncAPI can have channels.
| function findAsyncApiComponentTypes(components: any, specVersion: 'async2' | 'async3') { | ||
| const componentNames = | ||
| specVersion === 'async2' ? ASYNCAPI2_COMPONENT_NAMES : ASYNCAPI3_COMPONENT_NAMES; | ||
| return componentNames.filter( |
There was a problem hiding this comment.
Consider make it more readable, e.g. =>
const excluded = new Set([
'securitySchemes',
'servers',
'serverVariables',
'channels',
'operations',
]);
return componentNames.filter(
(item) => !excluded.has(item) && item in components
);|
|
||
| const componentsFiles: ComponentsFiles = {}; | ||
| const detectedVersion = detectSpec(asyncapi); | ||
| const specVersion: 'async2' | 'async3' = detectedVersion === 'async2' ? 'async2' : 'async3'; |
There was a problem hiding this comment.
| const specVersion: 'async2' | 'async3' = detectedVersion === 'async2' ? 'async2' : 'async3'; | |
| const specVersion: 'async2' | 'async3' = detectedVersion; |
package-lock.json
Outdated
| "integrity": "sha512-vMqyb7XCDMPvJFFOaT9kxtiRh42GwlZEg1/uIgtZshS5a/8OaduUfCi7kynKgc3Tw/6Uo2D+db9qBttghhmxwQ==", | ||
| "dev": true, | ||
| "license": "MIT", | ||
| "peer": true, |
There was a problem hiding this comment.
I don't see that some packages were added.
Could you please rebase changes from main.
Maybe you are using different npm version, could you please try npm install with 11.10.1.
| @@ -0,0 +1,33 @@ | |||
| asyncapi: '2.6.0' | |||
There was a problem hiding this comment.
I can see that e2e AsyncAPI examples were added, but I don’t see any snapshots or usage of those two descriptions.
Maybe some related changes were not pushed?
| @@ -0,0 +1,39 @@ | |||
| asyncapi: 3.0.0 | |||
There was a problem hiding this comment.
I can see that e2e AsyncAPI examples were added, but I don’t see any snapshots or usage of those two descriptions.
Maybe some related changes were not pushed?
| info: | ||
| title: Simple AsyncAPI Example | ||
| version: '1.0.0' | ||
| description: A simple AsyncAPI example for testing split command |
There was a problem hiding this comment.
| description: A simple AsyncAPI example for testing split command | |
| description: A simple AsyncAPI v2 example for testing split command |
tibisabau
force-pushed
the
feat/add-support-asyncapi23-split
branch
from
e9121a4 to
8875719
Compare
tibisabau
changed the title
2 participants
What/Why/How?
What: Added support for AsyncAPI 2.x and 3.x specifications to the
splitcommand, which previously only supported OpenAPI 3.x.Why: To enable users to split AsyncAPI definition files into modular directory structures, similar to the existing OpenAPI functionality. This addresses issue #2352.
How:
splitAsyncApiDefinition()orchestrator function to handle both AsyncAPI versionsiterateAsyncApiChannels()to split channels into separate files with proper $ref replacementsiterateAsyncApiOperations()for AsyncAPI 3 operations splittingiterateAsyncApiComponents()to handle component extraction with version-specific logicvalidateDefinitionFileName()to recognize AsyncAPI documentsReference
Resolves #2352
Testing
tests/e2e/split/asyncapi2-basic/asyncapi.yamlandtests/e2e/split/asyncapi3-basic/asyncapi.yamlScreenshots (optional)
N/A - CLI functionality
Check yourself
Security