Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

generator-asyncapi: append AsyncAPI specs to service specifications instead of replacing them

Open
  • Is something wrong?
#458 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
56/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
api, backend

Research direction

Start with packages/generator-asyncapi/src/index.ts around mergeAsyncApiIntoSpecifications (referenced at lines 203–209), then review the OpenAPI generator's handling of multiple paths and the specifications utilities. Add or update tests for merging two documents and rerunning the generator; done means both appear in the service spec view without duplicates or dropped entries, while a new service with one document still works. The issue leaves copied-file naming and service markdown behavior as design details to resolve.

Written by the indexing model from the issue text.

Description

Problem

When several AsyncAPI documents are merged into one service (same id and version in the generator config), only the last document processed shows up in the service's spec view.

Both files are copied into the service folder, but mergeAsyncApiIntoSpecifications keeps a single AsyncAPI entry:

  • array form: drops all existing type: asyncapi entries and appends one
  • object form: overwrites asyncapiPath

A two-entry array added by hand is reduced back to one on the next run.

Ref on main @ d061d78: packages/generator-asyncapi/src/index.ts L203-L209

Core already supports this: specifications can be an array of { type, path, name?, headers? } with several AsyncAPI entries (4.12.x and 5.x), and each gets its own page.

Proposal

  • When merging into an existing service of the same version, keep existing AsyncAPI entries with a different path and add or replace by path (normalise the legacy object form to the array form), using info.title as name.
  • Optionally accept path: string[] on a service entry, like the OpenAPI generator already does (generator-openapi/src/index.ts L386-L392 and its specifications utils), so one entry can take several documents.
  • Spec files need distinct basenames when copied into the service folder, or they overwrite each other. Handle or document that.

Done when

  • Two AsyncAPI documents merged into one service both appear in specifications and both render in the spec view.
  • Re-running the generator is idempotent (no duplicates, no dropped entries).
  • A new service still works with a single document.
  • Tests cover the merge and re-run cases.

Context

Raised by a community user at Taxfix who has one deployable with two AsyncAPI documents (hand-written domain events plus CLI-generated analytics events). They also noted the service page text comes from the first document processed, so they set generateMarkdown on that entry to show the other document's description. Worth keeping in mind when deciding how merged services pick their markdown and name.

Related

  • Companion issue: option to default message versions to the document's info.version.
  • #431 (closed): multiple OpenAPI files on one service, only one shown
  • event-catalog/eventcatalog#1117 (closed): introduced the specifications array
  • #407: output depends on the order AsyncAPI files are processed

The user has offered to test.

Dominant language
TypeScript
Stars
15
Forks
15
Avg merge
3m
Merged PRs (30d)
7

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from event-catalog/generators

All issues in event-catalog/generators

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.