[KITs] Remove API Plug-In in KITs

[danielmiehle]

Description

We will discontinue the use of the openAPI Plugin in the KITs to ensure the upgradeability of Docusaurus to version 3.0. We ask you to make the changes in your KITs as soon as possible so that we can use resources from the consortium to update Docusaurus.

Please note the following guidance:

Acceptance Criteria -- Update from Tomasz:

1. KITs API spec would follow configuration method, meaning you add each OpenAPI spec in the .tractusx metadata file as TRG states. No need to move files to /docs/api folder in repo.

2. KITs OpenAPI spec filenames need to follow special naming convention “kit_nameofthekit_openAPI.yaml”. The only part which you change is “nameofthekit”, you change it as you like the only caveat is to not use “_” underscore in that name.

3. Your Swagger UI docs would be available at following URL: [https://eclipse-tractusx.github.io/api-hub/repo/kit-nameofthekit-version/swagger-ui/]

4. Optional: For short APIs: Integrate your API in-line as a code block, for example: Agent KIT

Additional Information

After evaluation, the Swagger Hub does not fit our needs, so a new API Hub is to be set up:

https://github.com/eclipse-tractusx/api-hub
eclipse-tractusx/sig-infra#376

Task List

We have identified the following KITs that are affected by the change.

• [Business Partner KIT] Remove API Plug-In #971
• [Data Chain KIT] Remove API Plug-In #972
• [Digital Twin KIT] Remove API Plug-In #973
• [Modular Production KIT] Remove API Plug-In #974
• [MaaS KIT] Remove API Plug-In DRAFT #975
• [OSim KIT] Remove API Plug-In DRAFT #976
• [PCF KIT] Remove API Plug-In #977
• [Data Governance KIT] Remove API Plug-In #978

[danielmiehle]

@SebastianBezold @stephanbcbauer @jSchuetz88 :

Can you please review the issue and complement if necessary. Thanks!

[nhaenis]

AC:
Mandatory: Link your yaml file in an appropriate location in your development view .md file

What should such a link look like? Would it just be [Find here](./openApi/dcm/myYaml.yaml) or can someone please provide an example of this?
Thank you very much

[ClosedSourcerer]

#969

DCM added just this for the KIT 24.08 Release. See PR above.

[arnoweiss]

What does

without business domain (!)

mean? @danielmiehle

[danielmiehle]

Hi @arnoweiss ,

in the Catena-X Consoritum, we have assigned use cases to 3 business domains (e.g. sustainability, resiliency). I would no longer make this assignment in future.

[danielmiehle]

Please see updated guidance:

1. KITs API spec would follow configuration method, meaning you add each OpenAPI spec in the .tractusx metadata file as TRG states. No need to move files to /docs/api folder in repo.
2. KITs OpenAPI spec filenames need to follow special naming convention “kit_nameofthekit_openAPI.yaml”. The only part which you change is “nameofthekit”, you change it as you like the only caveat is to not use “_” underscore in that name.
3. Your Swagger UI docs would be available at following URL: [https://eclipse-tractusx.github.io/api-hub/repo/kit-nameofthekit-version/swagger-ui/]

[stephanbcbauer]

@danielmiehle isn't EDC missing in this list? Was there a list to follow?

[stephanbcbauer]

@danielmiehle isn't EDC missing in this list? Was there a list to follow?

no its not missing :)

[danielmiehle]

@stephanbcbauer : Could not find any API plug-in the connector kit. Can you please provide a link?

[arnoweiss]

So there's no central collection anymore but the swagger-pages are built from the reference implementations' repositories?

[danielmiehle]

@tomaszbarwicki: Can you please help and explain how the mechanism exactly works? Thanks!

[tomaszbarwicki]

So there's no central collection anymore but the swagger-pages are built from the reference implementations' repositories?

Hi @arnoweiss, @danielmiehle,

There is central collection at api-hub. You can visit currently hosted Swagger UI generated docs at https://eclipse-tractusx.github.io/api-hub/. Recently TRG 1.8 was published describing two options of getting your OpenAPI specs based docs hosted on api-hub github pages. The guidance above is strictly related to KITs APIs which follow slightly different concept in term of specs storage since there is no separate repos for them hence required an enhacement to current automation to generate and host swagger ui docs at api-hub as well.

@Siegfriedk it might be worth adding the KITs guidance to TRG..