Skip to content

fix: combine operations declared on the same path - #493

Merged
wolf4ood merged 1 commit into
eclipse-edc:mainfrom
wolf4ood:feat/merge_spec_improv
Oct 28, 2026
Merged

wolf4ood merged 1 commit into
eclipse-edc:mainfrom
wolf4ood:feat/merge_spec_improv

Conversation

@wolf4ood

Copy link
Copy Markdown
Contributor

What this PR changes

mergeOpenApiSpec merges the partial specs itself, with openapi-generator's MergedSpecBuilder in DEEP mode:

  • the spec files are merged in file name order;
  • operations declared on the same path by different specs are combined;
  • a conflicting definition (the same component name with a different content, or the same method on the same path)
    keeps the first one, and logs a warning.

The task options (--inputDir, --output, --outputDir, --infoTitle, --infoDescription, --infoVersion) are
unchanged.

openapi-generator is bumped from 7.19.0 to 7.26.0, which brings DEEP mode (since 7.24). buildSrc now depends on the
openapi-generator library, which the 7.26 Gradle plugin no longer exposes.

Why it does that

The default (REF) merge keeps one $ref per path, pointing to the last spec file that declares it. When two modules
declare the same path, the operations of one of them are lost. The input files were not sorted either, so which ones
were lost depended on the file system.

In the Connector, /v4/dataplanes has a GET from the data plane selector API and a PUT from the data plane
signaling registration API. The published management API spec lacks the PUT, and the OpenAPI verification fails at
random on unrelated PRs whenever the merge picks the other one.

The task no longer extends openapi-generator's GenerateTask:

  • REF merging needed a run of the openapi-yaml generator to resolve the $refs, whereas a DEEP merge is already
    self-contained;
  • in 7.26 GenerateTask runs through the worker API without waiting for the result, and needs a generator classpath
    that only openapi-generator's own plugin configures.

Further notes

  • Verified on the Connector's management API partial specs (./gradlew resolve on main):
    • 141 operations instead of 140 (adds PUT /v4/dataplanes), nothing removed;
    • no conflicting schema definitions;
    • identical output across runs.
  • The merged specs no longer go through the openapi-yaml generator. Inline schemas stay inline instead of being
    extracted into components (*_properties, *_inner), and unused schemas are kept. When a project adopts this
    version, the merged specs therefore differ from the published ones, and their API versions have to be bumped.
  • Tests: MergeOpenApiSpecTaskTest (operations on a shared path are combined; info and license are set).

Linked Issue(s)

Closes # <-- insert Issue number if one exists

Please be sure to take a look at the contributing guidelines and our etiquette for pull requests.

@wolf4ood
wolf4ood requested a review from a team as a code owner October 28, 2026 14:40
@wolf4ood wolf4ood added the enhancement New feature or request label Oct 28, 2026
@wolf4ood wolf4ood self-assigned this Oct 28, 2026
@wolf4ood
wolf4ood merged commit dd67e41 into eclipse-edc:main Oct 28, 2026
11 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants