feat(doc): update the verification and generation of OpenAPI spec files

[paullatzelsperger]

What this PR changes/adds

• applies the apiGroup property to all API-producing modules
• adds project properties to set the API title and description at runtime (-PapiTitle="some title" -PapiDescription="some description")
• Moves all OpenAPI related Github Action jobs out into a new workflow called apidoc.yaml that:
  • merges each API group into its own file
  • publishes all APIs to SwaggerHub

Why it does that

Improve API separation and documentation

Further notes

• publishing to SwaggerHub is currently a placeholder, because EDC doesn't have an account there yet.
• publishing to swaggerhub can be verified only after this PR is merged, because the necessary secret (SWAGGERHUB_TOKEN) is only present on the upstream repo
• embedded Swagger UI (docs/swaggerui) was deleted

Linked Issue(s)

Closes #2206
Closes #2163

Checklist

• added appropriate tests?
• performed checkstyle check locally?
• added/updated copyright headers?
• documented public classes/methods?
• added/updated relevant documentation?
• assigned appropriate label? (exclude from changelog with label no-changelog)
• formatted title correctly? (take a look at the CONTRIBUTING and Etiquette for pull requests for details)

[codecov-commenter]

Codecov Report

Base: 64.81% // Head: 64.66% // Decreases project coverage by -0.14% ⚠️

Coverage data is based on head (5ca2bdd) compared to base (1226275).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2209      +/-   ##
==========================================
- Coverage   64.81%   64.66%   -0.15%     
==========================================
  Files         828      830       +2     
  Lines       17452    17460       +8     
  Branches     1091     1091              
==========================================
- Hits        11312    11291      -21     
- Misses       5690     5719      +29     
  Partials      450      450              

Impacted Files	Coverage Δ
...nector/dataplane/client/RemoteDataPlaneClient.java	86.66% <0.00%> (-6.67%)	⬇️
...ceiver/http/HttpEndpointDataReferenceReceiver.java	85.29% <0.00%> (-6.14%)	⬇️
...actnegotiation/ContractNegotiationServiceImpl.java	94.44% <0.00%> (-5.56%)	⬇️
...ector/provision/http/HttpProvisionerExtension.java	88.23% <0.00%> (-2.68%)	⬇️
...ent/transferprocess/TransferProcessHttpClient.java	80.00% <0.00%> (-1.82%)	⬇️
.../org/eclipse/edc/junit/testfixtures/TestUtils.java	33.84% <0.00%> (-1.64%)	⬇️
...selector/client/RemoteDataPlaneSelectorClient.java	62.22% <0.00%> (-1.61%)	⬇️
...nector/dataplane/http/pipeline/HttpDataSource.java	81.81% <0.00%> (-1.52%)	⬇️
...ultipart/dispatcher/sender/IdsMultipartSender.java	82.41% <0.00%> (-0.38%)	⬇️
...pse/edc/event/cloud/http/CloudEventsPublisher.java	91.17% <0.00%> (-0.26%)	⬇️
... and 24 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[ndr-brt]

Could we wait to have the swagger hub uploaded and reachable from the docs site before removing the current swaggerui? Just to avoid 404s in the meantime.

[ndr-brt]

Does this branches: [ main ] need to be moved under the push block?
Otherwise this workflow will be executed for every push and this pull_request block would be useless.

[paullatzelsperger]

on the upstream repo, the only pushes should be merged PRs to main, so in reality it'll be the same thing. I copied the declaration from the verify.yaml.

[paullatzelsperger]

Could we wait to have the swagger hub uploaded and reachable from the docs site before removing the current swaggerui? Just to avoid 404s in the meantime.

Due to the fact that we don't have one single yaml file anymore, but one per api we cannot (easily) generate embedded swagger UI anymore, and if I leave the old one in, it'll be incorrect and won't reflect the code.
Also, we're talking about updating one or two lines in the docs repo, which makes this amount of work (investigate swagger UI with multiple files, creating another PR to remove the embedded swagger later) seem a bit much.

[ndr-brt]

@paullatzelsperger I don't say that we need to keep the process of ui generation, just to leave the static files there for some times until we have a replacement for them

[paullatzelsperger]

@paullatzelsperger I don't say that we need to keep the process of ui generation, just to leave the static files there for some times until we have a replacement for them

If we do that, it should be clear to anyone looking at it, that they're looking at a potentially outdated version of the API. But we can do it.

[paullatzelsperger]

@ndr-brt my latest commit brings back the static HTML for the swagger UI website.

[github-actions]

This pull request is stale because it has been open for 7 days with no activity.