docs: Document data-plane-api and small refactoring

[bscholtes1A]

What this PR changes/adds

Document data-plane-api extension:

• Add README file providing background and some technical documentation about the Data Plane API.
• Add OpenAPI documentation.

We take opportunity of this PR for a minor refactoring and some unit-tests improvement.

Why it does that

Provide missing documentation.

Linked Issue(s)

Contributes to #1382

Checklist

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

[codecov-commenter]

Codecov Report

Merging #1579 (5c7d728) into main (6d531cb) will increase coverage by 0.07%.
The diff coverage is 78.57%.

@@            Coverage Diff             @@
##             main    #1579      +/-   ##
==========================================
+ Coverage   67.72%   67.79%   +0.07%     
==========================================
  Files         754      759       +5     
  Lines       16336    16386      +50     
  Branches     1047     1049       +2     
==========================================
+ Hits        11063    11109      +46     
- Misses       4794     4798       +4     
  Partials      479      479              

Impacted Files	Coverage Δ
...ctor/dataplane/api/response/ResponseFunctions.java	83.33% <0.00%> (ø)
.../api/controller/DataPlaneControlApiController.java	76.92% <62.50%> (+13.28%)	⬆️
...e/api/controller/DataPlanePublicApiController.java	78.26% <87.50%> (+0.98%)	⬆️
...connector/dataplane/api/DataPlaneApiExtension.java	100.00% <100.00%> (ø)
...aplane/api/controller/DataFlowRequestSupplier.java	100.00% <100.00%> (ø)
...lane/api/validation/TokenValidationClientImpl.java	72.22% <100.00%> (ø)
...tor/configuration/fs/FsConfigurationExtension.java	55.00% <0.00%> (ø)
...datamanagement/asset/service/AssetServiceImpl.java	100.00% <0.00%> (ø)
...tamanagement/asset/service/EventAssetListener.java	100.00% <0.00%> (ø)
...nt/policy/service/PolicyDefinitionServiceImpl.java	94.11% <0.00%> (ø)
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6d531cb...5c7d728. Read the comment docs.

[florianrusch-zf]

@bscholtes1A I am currently wondering whether the async push case should also be described in the use cases. Doesn't the API also play a role in this?

[bscholtes1A]

@bscholtes1A I am currently wondering whether the async push case should also be described in the use cases. Doesn't the API also play a role in this?

All "provider push" transfers are asynchronous, including the one that I described in the markdown file. This is why the Control API exposes a "getTransferState" endpoint which enables to track the state of an on-going asynchronous data transfer.

[paullatzelsperger]

removing myself, as there are already sufficient reviewers

[florianrusch-zf]

All "provider push" transfers are asynchronous, including the one that I described in the markdown file. This is why the Control API exposes a "getTransferState" endpoint which enables to track the state of an on-going asynchronous data transfer.

ok, but I was speaking about the async-async push 😅 Means on provider side happens a provisioning first. Don't know if this flow fits into this documentation or if there is somewhere a better place for it.

[bscholtes1A]

All "provider push" transfers are asynchronous, including the one that I described in the markdown file. This is why the Control API exposes a "getTransferState" endpoint which enables to track the state of an on-going asynchronous data transfer.

ok, but I was speaking about the async-async push 😅 Means on provider side happens a provisioning first. Don't know if this flow fits into this documentation or if there is somewhere a better place for it.

@florianrusch-zf are you taking about the http-provisioner stuff? If yes I think this one should be better documented in the http-provisioner extension. @ndr-brt what do you think?

[ndr-brt]

All "provider push" transfers are asynchronous, including the one that I described in the markdown file. This is why the Control API exposes a "getTransferState" endpoint which enables to track the state of an on-going asynchronous data transfer.
ok, but I was speaking about the async-async push sweat_smile Means on provider side happens a provisioning first. Don't know if this flow fits into this documentation or if there is somewhere a better place for it.

@florianrusch-zf are you taking about the http-provisioner stuff? If yes I think this one should be better documented in the http-provisioner extension. @ndr-brt what do you think?

agree, it's not strictly related to data-plane